chord

README

Chord

📖 Docs site: https://keakon.github.io/chord/ · 中文版： README_CN.md

Calm AI coding in your terminal. A lightweight, local-first coding agent built for long sessions that do not fall over, model setups you can swap at runtime, and remote operation when you cannot be at the keyboard.

• Companion gateway: keakon/chord-gateway — drive Chord from WeChat, Feishu, and other chat surfaces

Why Chord

Start with the core experience you notice immediately:

• Stable for the long haul. Chord can summarize earlier turns before a long conversation gets too large for the model, while preserving what is needed to continue. No more "wait, did it forget?".
• You see the network state. While waiting for a model response, Chord shows precise request status and elapsed wait time. Never wonder if it is stuck again.
• Keyboard-first, Vim-style. Insert / Normal modes, message search, Vim-flavoured navigation, automatic input-method switching across modes. Quitting takes two taps so you do not lose work to a stray Ctrl+C.
• Hot-swap model setups. Group models into reusable pools (fast, thinking, cheap, …); switch the active pool at runtime via /models or Ctrl+P. Each agent picks its own pool; the runtime falls back through the ordered list automatically.
• Extremely lightweight. Low memory and CPU footprint. Power-aware on macOS: prevents idle sleep while work is active, lets the system sleep again when idle.
• Drive it remotely. chord headless exposes a stdio JSONL control plane; pair with chord-gateway to operate Chord from any chat surface — even from your phone when you are away from the desk.

Out of the box, you also get these quality-of-life upgrades:

• LSP-backed code awareness — live diagnostics and definition / references / implementation lookups via your local language servers.
• Multimodal input — paste images from the clipboard, attach files, preview in supported terminals.
• Codex quota visibility — real-time remaining-quota and reset-time display for OpenAI Codex subscriptions.

Once you want to go further, Chord also supports these advanced workflows:

• Multi-agent collaboration — a main agent with focused SubAgents, each with its own context, switchable via Shift+Tab.
• Parallel work via git worktrees — chord --worktree feat-auth spins up an isolated working copy so several tasks on the same repo do not stomp on each other.

Three-step setup

1. Install

If you already have Go 1.26+ installed:

go install github.com/keakon/chord/cmd/chord@latest

If you do not have Go 1.26+, download a prebuilt binary from GitHub Releases. Pick the archive for your OS/architecture, extract it, put chord on your PATH, and run:

chord --version

2. Configure provider, model pool, and credentials

mkdir -p ~/.config/chord && chmod 700 ~/.config/chord
cat > ~/.config/chord/config.yaml <<'YAML'
providers:
  openrouter:
    type: chat-completions
    api_url: https://openrouter.ai/api/v1/chat/completions
    models:
      openai/gpt-5.5:
        limit:
          context: 400000
          input: 272000
          output: 128000
        modalities:
          input: [text, image]
model_pools:
  default:
    - openrouter/openai/gpt-5.5
YAML
cat > ~/.config/chord/auth.yaml <<'YAML'
openrouter:
  - "$OPENROUTER_API_KEY"
YAML

3. Run from your project

cd my-project && chord

For other OpenRouter models or different OpenAI-compatible providers, see Quickstart. Read model limits in this order: limit.context is the total window; for most models, input + requested output just needs to fit there. If a provider also lists a separate input cap (some GPT models do), add limit.input; otherwise Chord falls back to limit.context. limit.output is the model's own output capacity. Chord's gpt-5.5 examples use context=400000, input=272000, output=128000; the default requested output cap (max_output_tokens) is still 32000, so real requests use the smaller output limit unless you raise it. See Glossary for the related terms.

Release download notes

GitHub Releases provide prebuilt binaries for supported platforms. On macOS, the downloaded binary may be blocked on first run because the file came from the internet and is not notarized. If that happens, remove the quarantine attribute and make the binary executable:

xattr -dr com.apple.quarantine /path/to/chord
chmod +x /path/to/chord
/path/to/chord --version

If macOS still blocks it, add a local ad-hoc signature:

codesign --force --sign - /path/to/chord

For example, if you installed Chord at /usr/local/bin/chord, replace /path/to/chord with /usr/local/bin/chord.

Documentation

• Docs home
• Getting started: Quickstart · Usage · Glossary
• Reference: CLI · Configuration & Auth · Keybindings · Paths · Environment variables · Platform support
• Going further: Customization · Hooks · Examples
• Integration: Headless
• Safety: Permissions & Safety
• Troubleshooting: Troubleshooting

Project links

• Companion: keakon/chord-gateway
• Contributing
• Changelog
• Issues

Platform support

Chord is developed and tested primarily on macOS. Linux works well; Windows mostly works but may have undiscovered bugs. Some features (prevent_sleep) are macOS-only and silently no-op elsewhere. See Platform support for the per-feature matrix.

License

MIT License. See LICENSE.