term2

term2 is an open-source AI assistant for coding and terminal work.

Read a codebase, edit files, and run commands locally or over SSH. Choose your model, delegate work to subagents, and return to saved conversations.

Website & documentation · First run · Changelog

What you can do

• Work with a codebase. Trace a failure, implement a feature, review a change, and run tests.
• Choose your models. Connect a supported hosted provider or a local model endpoint. Switch models with /model and manage connections with /providers.
• Delegate tasks. Use subagents for research, implementation, or review, including background work.
• Keep working across sessions. Resume a conversation after a break, fork it to try another approach, or work with a remote project over SSH.

Get started

You need Node.js 24 or newer, an interactive terminal, and access to a model provider.

npm install --global @qduc/term2
term2 --version

On Linux, sandboxed shell commands also need bubblewrap (bwrap), socat, and ripgrep (rg). Install them with your OS package manager. Shell execution fails closed when the enabled sandbox is unavailable. See installation for platform details.

Choose one authentication path:

# ChatGPT / Codex: complete the browser login
term2 --codex-login

# Or OpenAI API: set your own API key in this shell
export OPENAI_API_KEY="your-api-key"

For other providers, follow provider setup. OpenRouter and Grok are built in; add direct Anthropic, Gemini, and local endpoints through /providers. An API key alone does not register a custom provider. Hosted providers receive the conversation context and tool results used for your request; their billing and account limits apply.

Open a project and select a model from the provider you authenticated:

cd /path/to/your/project
term2 --model

Ask it to explain the project, fix a bug, or implement a feature. term2 can apply valid local workspace edits without a prompt; shell commands require approval under the default interactive settings. Review the resulting diff before committing.

This README tracks main; npm releases may lag behind it. Check term2 --version and the changelog when following documentation for a newer feature.

Useful commands

To…	Use…
Switch models	/model or Ctrl+O
Restart the built CLI	/restart (or /restart stop to stop background work)
Manage provider connections	/providers
Resume a conversation	term2 --resume; term2 --resume ls lists saved sessions
Try another approach	term2 --resume <session-id> --fork
Work over SSH	term2 --ssh user@host --remote-dir /path/to/project
Ask a one-off question	term2 "Explain the difference between a merge and a rebase"

Continue a saved session headlessly with term2 --resume <session-id> "Follow-up prompt" (or use last instead of an ID). Add --fork to keep the original session unchanged.

Every session uses the same default experience: a minimal prompt with subagent delegation. Choose models and reasoning effort with /model and /effort; there is no profile chooser. Legacy profile inputs and saved session metadata remain compatible; see profile internals.

A command-line prompt runs non-interactively, with tool execution disabled by default. --auto-approve enables tools without interactive confirmation; use it only when you intend unattended execution. See scripting and SSH setup.

The optional Discord bridge attaches to existing opted-in terminal sessions. Start with term2 discord --help. Replies require explicit discord_send; status, approvals and questions stay local. Live mobile checks covered routing, explicit replies, local approval, pause/stop and bridge restart. See the guide for tested scope and remaining limits.

/restart reloads the built CLI in place and resumes the conversation, recovering durably queued text (not unsaved editor drafts). It requires POSIX Node with process.execve support, a built dist/cli.js entry, and no Node flags, loaders, or NODE_OPTIONS. Live background work blocks restart unless you explicitly use /restart stop; active workspace leases reset to home scope. Finish foreground shell commands and pending input confirmations first. See session restart for recovery limits.

Approvals and sandbox

Interactive sessions default to shell auto-approval off and an enabled shell sandbox. You can change these settings, so the active configuration matters. The sandbox constrains shell commands; it does not cover providers, external MCP servers, or every tool.

Read-only gateway sessions require sandboxed shell execution: disabling the sandbox, requesting an unsandboxed command, or using an SSH execution context does not bypass the read-only restriction.

See approvals and sandbox boundaries for the policies and their limits.

Status

Supported:

• The interactive TUI and headless runs, including --resume and JSON output.
• The web/server host (term2 serve) with the separately built web-client/ from the same source revision. See gateway setup for pairing, BFF keys and remote-access limits.
• The ACP subset described below: stable ACP v1 for editors such as JetBrains Air and Zed, and experimental ACP v2, an upstream draft verified only against the SDK 1.4.0 reference client.
• The Discord bridge for opted-in interactive sessions, subject to the tested scope and limits in its guide.

Experimental, and may change between releases: SSH remote projects and the standalone control socket (term2 control).

Point an ACP client at:

term2 acp --provider <provider> --model <exact-model-id>

The same command serves v1 and v2; the version comes from the client's initialize request. Connect the client to stdin/stdout; diagnostics go to stderr. ACP v2 requires the shell sandbox and sends approval-required tools to the client. ACP v1 defaults to the same behavior, and its session-local approval mode can switch to Assisted or turn the sandbox off. See the ACP reference for session replay, client versions and acceptance limits.

Develop from source

Use Node 24 and pnpm 11:

git clone https://github.com/qduc/term2.git
cd term2
pnpm install --frozen-lockfile
pnpm build
pnpm start --help

Read AGENTS.md before changing code. Use focused tests for the affected area; integration and provider tests have separate commands in package.json.

The documentation site lives in website/:

pnpm --dir website install --frozen-lockfile
pnpm --dir website build
pnpm --dir website preview

The separate private Next.js web-client/ app connects to the term2 serve gateway. It is not included in the npm CLI package; frontend updates require updating and rebuilding that app separately. Gateway backend fixes ship with the CLI. See gateway setup.

License

MIT.