coded

A terminal coding agent harness, written in Go. See adr/ for the architectural decisions behind it.

Warning: v0.1 has no context compaction — a long session hard-fails once it hits the model's context limit, and the fix is /clear or /model.

Install

With a Go toolchain:

go install github.com/mchalapuk/coded/cmd/coded@latest

Or grab a prebuilt archive from the releases page and put the binary on your PATH:

tar -xzf coded_v0.1.0_darwin_arm64.tar.gz
install -m 0755 coded /usr/local/bin/coded

Archives are published for macOS and Linux on amd64 and arm64, alongside a checksums.txt. There is no native Windows build: the Bash tool runs commands through sh -c, so it needs a POSIX shell — under WSL or Git Bash, install with go install.

Build

make             # clean, fmt, vet, tidy, race, build, regenerate the prompt
                 # dump, and test -- everything short of a release archive

Configure

API keys

coded auth login                       # prompts for the Anthropic key, stores it securely
coded auth login --provider openai     # same, for OpenAI
coded auth status [--provider ...]     # show which key is active and where it came from
coded auth logout [--provider ...]     # remove a stored key

coded auth login stores the key in the OS-native credential store (macOS Keychain, Windows Credential Manager, Linux Secret Service). If none is available — e.g. a headless Linux box with no D-Bus session — it falls back to ~/.coded/credentials.json with 0600 permissions and prints a warning. API keys are never read from config.json or settings.json, so those files are safe to commit.

Alternatively, set an environment variable, which always takes precedence over anything stored via coded auth:

export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...

Settings

~/.coded/config.json holds non-secret defaults:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-5-20250929",
  "permission_mode": "default"
}

Project-level overrides (permission rules, model) go in .coded/settings.json at the root of a repo:

{
  "permission_mode": "default",
  "allow": ["Read", "Grep", "Glob", "Bash(git status)", "Bash(git diff*)"],
  "deny": ["Bash(rm -rf *)"]
}

Drop a CODED.md, AGENTS.md, and/or CLAUDE.md file in your repo root for project-specific instructions — any that exist are picked up automatically and included in every request (concatenated, in that precedence order, if more than one is present). They're re-read from disk and injected fresh on every turn rather than baked into the system prompt once, so edits take effect on the very next turn — including mid-session — without restarting, and without invalidating the prompt cache built up over a long conversation.

Use

coded                              # interactive TUI in the current directory
coded -p "explain this repo"       # one-shot, prints the answer and exits
coded --continue                   # resume the most recent session here
coded --resume <session-id>        # resume a specific session
coded --model <name>               # override the model for this run
coded --permission-mode <mode>     # default|accept-edits|bypass|plan
coded sessions list                # list saved sessions
coded auth login|logout|status [--provider anthropic|openai]   # see Configure
coded --version
coded --help

--permission-mode plan is investigate-only: no mutations. One-shot mode (-p) has no interactive prompt, so any call that would ask for approval is denied and explained instead; --permission-mode accept-edits or bypass gets most calls through. A target outside the project root still asks -- and so still gets denied under -p -- even with bypass; add an explicit allow rule in .coded/settings.json for a call that needs to reach outside the root non-interactively.

If you built from source rather than installing, the binary is bin/coded.

coded -p exits with a distinct code depending on why a run failed, so a script can branch without scraping stderr:

Code	Meaning
0	Success
1	Generic failure (bad config, invalid request, unclassified error)
2	Authentication failure — run coded auth login
3	Transient provider failure that persisted after retrying (rate limit, overloaded, server, network)

Slash commands

Inside the TUI:

/clear                start a new conversation
/help                 show the command list
/login [provider]     log in and store an API key
/logout [provider]    remove a stored API key
/model [family]       show the model menu, or set it directly (e.g. /model Sonnet)
/quit                 quit coded

Inspect the prompt

make dump-prompt      # or: go run ./cmd/promptdump

Runs a scripted fake agent conversation through the real agent loop, tool registry, and permission engine — only the model itself is mocked — and writes everything it saw (system prompt, tool schemas, the full message history, and the react-tag reminders injected between turns) to prompts/agent-run.txt. The output is deterministic and meant to be committed so that the diff in the effective prompt can be reviewed.

Release

make dist        # cross-compiled release archives + checksums in dist/

make dist stamps the current git describe into the binary, so coded --version reports the tag it was cut from. It only writes dist/; publishing is a separate, deliberate step:

git tag -a v0.1.0 -m "v0.1.0" && git push origin v0.1.0
make dist
gh release create v0.1.0 dist/*.tar.gz dist/checksums.txt