GitHub - ExpressGradient/laser: shell coding agent

4 min read Original article ↗

Laser

Laser is a small, terminal-based coding agent you run inside a repository. It can:

  • read and edit files in the repo
  • run shell commands (tests, formatters, build steps)
  • iterate with you on changes, keeping the workflow repo-first

It’s built on kosong and supports multiple model providers.

Quick start (no clone required)

1) Install uv

If you don’t have it yet, install uv (recommended Python package manager):

2) Run Laser from GitHub

You can run Laser directly from this repo without downloading it:

uvx --from git+https://github.com/ExpressGradient/laser laser

Or install it first (so you can run laser directly):

uv tool install git+https://github.com/ExpressGradient/laser
laser

To upgrade later:

Useful flags (work with either uvx ... laser or laser):

# show help
laser --help

# pick a model
laser --model openai/gpt-5.2-codex

# run in a different repo
laser --cwd /path/to/your/repo

# cap tokens (Anthropic only; other providers ignore this)
laser --max-tokens 4096

# non-interactive single-shot mode
laser --prompt "Run tests and summarize failures"

# planning mode (write a checklist plan file before acting)
laser --plan

Notes:

  • --cwd changes the working directory Laser operates in (where it reads/writes files and runs commands).

Using Laser effectively

Basic workflow

  1. Start Laser in your repo.
  2. Describe what you want to change.
  3. Laser will inspect the repo, make edits, and run commands as needed.
  4. Review diffs and iterate.

Laser is intentionally conservative:

  • it prefers rg for search
  • it avoids destructive commands (e.g. rm -rf, git reset --hard)
  • it checks diffs and file contents after edits

If you want Laser to always start by writing a plan checklist file, use --plan.

Multi-line input

If your message ends with a trailing backslash (\), Laser will continue reading lines until you send a line without \.

Example:

Write a script that:\
- scans all Python files\
- prints unused imports\
- and suggests fixes

Interactive commands

In interactive mode, Laser supports these slash commands:

  • /usage — print cumulative token usage for the current session
  • /reset — clear the current chat history and start a fresh conversation context
  • /quit — exit

You can also run local shell commands directly by prefixing your input with !:

  • !<command> — run <command> in your current working directory and print stdout/stderr

Example:

Repository instructions (AGENTS.md)

If your repository has an AGENTS.md at its root, Laser will read it at the start of each task and follow those repo-specific rules (unless they conflict with Laser’s own safety/workflow rules).

This is useful for documenting things like:

  • how to run tests
  • formatting/linting commands
  • code style conventions
  • release steps

Models and providers

Laser supports multiple model backends (configured in main.py). Select one with --model.

uvx --from git+https://github.com/ExpressGradient/laser laser --model openai/gpt-5.2-codex

If a provider requires environment variables (API keys), set them before running. Common examples:

  • OpenAI: OPENAI_API_KEY
  • Anthropic: ANTHROPIC_API_KEY
  • Google: GOOGLE_API_KEY

(Exact names depend on the provider SDK/config; check provider docs.)

Providers are selected via the <provider>/<model> format. Examples:

laser --model anthropic/claude-opus-4-5
laser --model google/gemini-3-pro-preview
laser --model chat/glm-4.7

For OpenAI-compatible legacy models (like chat/*), set the base URL env before running if you're targeting a non-OpenAI endpoint (for example, OPENAI_BASE_URL).

Development

If you are working on Laser itself, run it locally:

Or via the console script from your checkout:

Troubleshooting

Missing ripgrep (rg)

Laser requires ripgrep (the rg command). If it's not installed, Laser will exit at startup with a message pointing you to install it.

Shell commands fail

Laser surfaces stderr from failed commands. If something fails, try:

  • re-running the exact command manually
  • checking that required tools are installed
  • ensuring you’re in the correct directory (--cwd)

The agent is operating in the wrong directory

Run with:

uvx --from git+https://github.com/ExpressGradient/laser laser --cwd /path/to/repo