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. Use /plan for read-only exploration.
• 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 20 or newer (Node 24 recommended), 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. Standard mode can apply valid local workspace edits without a prompt; shell commands require approval under the default interactive settings. Review the resulting diff before committing. Enter /plan for read-only exploration, then /plan again to return to Standard mode.

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.

Bare is the default minimal-prompt profile with subagent delegation. Standard is retired: old standard/full profile selections and saved Standard sessions now resolve to Bare. The former Lite options (--lite, -l, /lite, and --profile lite) now select Bare too.

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 (candidate) attaches existing opted-in terminal sessions. Start with term2 discord --help. Replies require explicit discord_send; status, approvals and questions stay local. Live Discord/mobile validation is still outstanding.

/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 (Node 24 recommended), 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.

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.