Albatross

<h1 align="center">Albatross</h1> <p align="center"> <strong>A small, terminal-first coding harness. Bring your own model, your own key, or your own MCP server.</strong> </p> <p align="center"> <a href="#install">Install</a> &middot; <a href="#run-it">Run it</a> &middot; <a href="#first-session">First session</a> &middot; <a href="#providers">Providers</a> &middot; <a href="#tools-and-commands">Tools &amp; commands</a> &middot; <a href="#cost-and-credentials">Cost &amp; credentials</a> &middot; <a href="#going-further">Going further</a> &middot; <a href="#configuration">Configuration</a> &middot; <a href="#troubleshooting">Troubleshooting</a> </p> <p align="center"> <a href="https://github.com/morganlinton/Albatross/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/morganlinton/Albatross/actions/workflows/ci.yml/badge.svg"></a> <a href="https://crates.io/crates/albatross-cli"><img alt="crates.io" src="https://img.shields.io/crates/v/albatross-cli?label=crates.io&color=2563eb"></a> <img alt="Rust" src="https://img.shields.io/badge/Rust-1.86%2B-dea584"> <img alt="Version" src="https://img.shields.io/badge/version-2.5.0-111827"> <img alt="Providers" src="https://img.shields.io/badge/providers-Ollama%20%7C%20LM%20Studio%20%7C%20MLX%20%7C%20llama.cpp%20%7C%20OpenRouter%20%7C%20OpenAI%20%7C%20Anthropic%20%7C%20Grok-2563eb"> <img alt="Apple Silicon" src="https://img.shields.io/badge/Apple%20Silicon-optimized-111827"> <img alt="License MIT" src="https://img.shields.io/badge/license-MIT-111827"> </p> <p align="center"> <img alt="Albatross writing and running a local coding session" src="docs/assets/demo/agent-session.gif" width="920"> </p> <p align="center"> <a href="docs/assets/demo/agent-session.mp4">Session video (mp4)</a> </p>

---

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 <name> — 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 <task> 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 <goal> 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__<server>__<tool> 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):

brew install morganlinton/tap/albatross

Cargo (any platform with Rust 1.86+):

cargo install albatross-cli    # installs the `albatross` binary

From source (Rust 1.86+):

git clone https://github.com/morganlinton/Albatross.git
cd Albatross
cargo build --release    # binary at target/release/albatross

---

Run it

Launch the interactive session:

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:

   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):

   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 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:

/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:

/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, start it, and pull a coding model:

   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:

   albatross
   

LM Studio, MLX, and llama.cpp work the same way — see Providers for their ports and start commands.

Tip: switch providers mid-session with /provider <name>, and run /doctor if a provider won't connect. /backend remains an alias.

---

First session

> 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 <label> scores manual closes from shipcheck (not the separate /play score fixture report).
• /plan <intent> drafts a spec; /iterate <goal> runs a generate→evaluate loop where a separate critic grades each pass against a rubric.
• /play fix-failing-test runs a bundled demo in an isolated sandbox so you can try a real agent loop without touching your repo.
• Ctrl-J for newline; Enter submits.
• albatross --continue resumes the most recent session in the cwd.

---

Providers

| Provider | Default URL | Notes | |---------|-------------|-------| | ollama | http://localhost:11434/v1 | Easiest setup; mature tool-call templates | | lm-studio | http://localhost:1234/v1 | GUI model browser; explicit load / unload | | mlx | http://localhost:8080/v1 | Fastest inference on Apple Silicon (via mlx_lm.server) | | llamacpp | http://localhost:8080/v1 | Direct GGUF serving (via llama-server) | | openrouter | https://openrouter.ai/api/v1 | Cloud A/B with /compare; access to frontier models and Fusion | | openai | https://api.openai.com/v1 | Direct provider access with your own key | | anthropic | https://api.anthropic.com/v1 | Native Messages API with your own Anthropic API key | | openai-codex | https://chatgpt.com/backend-api/codex/responses | ChatGPT/Codex subscription OAuth via /login openai-codex | | grok | https://cli-chat-proxy.grok.com/v1 | SuperGrok / X Premium+ OAuth via /login grok (browser or device-code) |

Switch at runtime with /provider <name>. Endpoint overrides: OLLAMA_BASE_URL, `LM_STUDIO_BAS