Albatross

A small, terminal-first coding harness. Bring your own model, your own key, or your own MCP server.

Install · Run it · First session · Providers · Tools & commands · Cost & credentials · Going further · Configuration · Troubleshooting

CI crates.io Rust Version Providers Apple Silicon License MIT

Albatross writing and running a local coding session

Session video (mp4)

--- ## What it is A coding agent that lives in your terminal. Bring your own **API key** (OpenAI or OpenRouter) or point it at a **local model** (Ollama, LM Studio, MLX, llama.cpp) — same tools, same commands, same session log either way. It ships with the usual tool kit — read, edit, grep, shell, run tests — plus a few that aren't usual: - **Local or cloud, one TUI.** Switch providers mid-session with `/provider ` — the tools, commands, and session log don't change. - **Per-turn cost on the status line.** `$0.003 this turn · $0.41 session` when pricing is known or reported by the provider. Local turns just show tokens. - **OpenRouter Fusion, one command away.** `/fusion on` switches to the `openrouter/fusion` alias for deliberative work; `/fusion tool` attaches Fusion to a chosen OpenRouter coding model for hard reviews, architecture tradeoffs, and high-stakes debugging. - **Transparent multi-model routing.** `/route select ` scores every configured coder candidate, estimates cost, applies explicit policy limits, and shows the chosen model, effort, confidence, alternatives, and reasons. - **Routed plans.** `/plan route ` asks a configured planner model to break work into a low/medium/high task graph, saves it to `.albatross/plan.json`, and `/plan execute` runs ready tasks through the configured coder tiers. - **Real undo.** `/undo` reverts the last agent turn's file mutations, including files the agent created or files that weren't tracked when the turn started. - **Session paths.** `/path fork` branches the conversation and workspace so you can try two fixes, diff them, and `/path pick` the winner — no worktree required. - **Plan, then grade the work.** `/plan` expands a one-line intent into a spec; `/iterate` runs a generate→evaluate loop where a *separate* critic agent scores each pass against a rubric and feeds back until it clears the bar — the generator never grades itself. - **Reset over compaction.** `/reset` writes a handoff artifact and starts a clean session seeded with it — better coherence on long tasks than summarizing in place. - **MCP-native.** Drop servers into `mcpServers` in your config; their tools show up as `mcp____` to the model on next launch. - **Language-neutral extensions.** Trusted subprocesses can register custom model tools, slash commands, and lifecycle event listeners over JSON-RPC. Config changes revoke trust automatically. - **Installable packages.** Install npm or Git packages containing extensions, skills, prompt templates, and terminal themes. npm lifecycle scripts stay disabled, and packaged executables still require workspace trust. - **Portable Agent Skills.** Discover standard `SKILL.md` bundles from project, user, npm, and Git locations; invoke them with `/skill:name`, or let the model load matching instructions progressively through an approval-aware tool. - **Embeddable Rust SDK.** Build an in-process agent session with structured streaming events, conversation snapshots, cancellation, approvals, built-in or custom tools, and the same providers and Agent Skills as the CLI. - **`/auth` instead of `.env`.** Paste API keys once into a `0600` file under `~/.config/albatross/`. Env vars still win when set. - **Approval gates you can live with.** Every mutating call shows you the diff first, with `allow once / allow session / always allow` caching. --- ## Install **Homebrew (macOS):** ```bash brew install morganlinton/tap/albatross ``` **Cargo (any platform with Rust 1.86+):** ```bash cargo install albatross-cli # installs the `albatross` binary ``` **From source** (Rust 1.86+): ```bash git clone https://github.com/morganlinton/Albatross.git cd Albatross cargo build --release # binary at target/release/albatross ``` --- ## Run it Launch the interactive session: ```bash albatross ``` > From a source checkout without installing, use `cargo run --release` instead. The first launch runs a short setup wizard (it writes `agent.config.json` — provider, model, approval policy). Skip it with `ALBATROSS_NO_WIZARD=true`. Every launch after that opens straight into a session. Albatross talks to **one provider at a time** — pick the path that fits. ### Path A — Cloud API key *Fastest to start, frontier-model quality, nothing to install locally.* 1. Set your key — Anthropic, OpenAI, **or** OpenRouter: ```bash export ANTHROPIC_API_KEY=sk-ant-... # or export OPENAI_API_KEY=sk-... # or export OPENROUTER_API_KEY=sk-or-... ``` 2. Launch, then select the provider in the first-run wizard (or any time with `/provider anthropic`): ```bash albatross ``` Prefer not to put the key in your environment? Launch first, then run `/auth set anthropic` inside the app and paste it once — it's stored in a `0600` file under `~/.config/albatross/`. Cost per turn and per session shows live on the status line. The Anthropic provider uses the documented Claude API and your `ANTHROPIC_API_KEY`. It does **not** offer Claude.ai OAuth or use a Pro, Max, Team, or Enterprise subscription allowance; Anthropic's [Agent SDK guidance](https://code.claude.com/docs/en/agent-sdk/overview) requires prior approval before third-party products can offer subscription login or rate limits. ### Path A2 — ChatGPT / Codex subscription login If you want to use a ChatGPT/Codex subscription instead of OpenAI API billing, log in with OAuth inside the TUI: ```text /login openai-codex /provider openai-codex ``` This is intentionally separate from `/auth set openai`: `openai` uses an `OPENAI_API_KEY` and the public OpenAI API, while `openai-codex` stores a refreshable ChatGPT OAuth token in `auth.json` and talks to the Codex Responses backend. ### Path A3 — Grok / SuperGrok subscription login Use a SuperGrok or X Premium+ subscription through browser or headless device-code OAuth, with no `XAI_API_KEY`: ```text /login grok /provider grok ``` Pick **1) Browser login** (opens the system browser + local callback) or **2) Device-code login** for SSH/headless. Tokens land in `auth.json` under `grok` and refresh automatically. Default model is `grok-4.5`. `/model` exposes the static agent-ready catalog (`grok-4.5`, `grok-4.3`, `grok-build-0.1`), same as pi — it does not scrape xAI's full `/models` list. ### Path B — Local model *Private, free, offline — runs entirely on your machine.* 1. Install [Ollama](https://ollama.com), start it, and pull a coding model: ```bash brew install ollama brew services start ollama ollama pull qwen2.5-coder:7b ``` 2. Launch — Ollama is the default provider, so there's nothing else to set: ```bash albatross ``` LM Studio, MLX, and llama.cpp work the same way — see [Providers](#providers) for their ports and start commands. > **Tip:** switch providers mid-session with `/provider `, and run > `/doctor` if a provider won't connect. `/backend` remains an alias. --- ## First session ```text > what files are in src/? Listed src/ (24 files) src/ has 24 Rust files: main.rs is the entry point (input loop, banner, warmup); agent.rs runs the chat-completions loop; backends.rs handles the providers; tools/ contains the tool implementations… 1.2k in · 87 out · $0.0003 this turn · $0.0003 session > add a function in src/util.rs that lowercases a string and trims it Read src/util.rs Edited src/util.rs --- src/util.rs +++ src/util.rs @@ ... +pub fn normalize(input: &str) -> String { + input.trim().to_lowercase() +} Apply? [y/n/a]: y checkpoint saved (1 file) — /undo to revert 3.4k in · 412 out · $0.001 this turn · $0.0013 session ``` A handful of moves worth knowing right away: - `/mode explore | edit | ship | review` toggles tool + approval + step-budget presets. - `/undo` reverts the last turn's file mutations. - `/path fork` branches the session to try an alternate approach; `/path switch`, `/path diff`, and `/path pick` compare and merge paths. - `/shipcheck` summarizes git state; `/handoff` drafts a commit message, changelog bullets, and a release post from local context. - `/ship` turns that into a last-mile preflight, local commit, and push path: readiness verdict, blockers, commit-message draft, guarded `git commit`, and guarded `git push`; `/ship pr` opens a draft pull request through GitHub CLI when available, and `/ship status` summarizes open PR checks/review state. - `/scorecard` shows global quality PRs shipped; `/ship pr` closes a PR unit with readiness/test evidence. `/scorecard close