tcode CLI Command Reference

User-Facing Commands

`tcode`

Starts a new normal session. Launches the server and opens display, edit, tree, and permission panes in the current tmux session. A unique 8-character session ID is generated automatically. Session files persist in ~/.tcode/sessions/{id}/.

Use --web-only to create a new web-only session. Web-only sessions keep the same UI, but only web research, current time, and delegation tools are available; local filesystem tools, shell commands, LSP, skills, and project instructions are not loaded. web_fetch hostname permissions are auto-granted (a session-scoped wildcard visible in the permission tree and revocable). The mode is stored with the session and is shown by tcode sessions and the interactive session picker.

If no config file exists at ~/.tcode/config.toml, tcode automatically launches the tcode config wizard in interactive terminals, writes the file, and exits — run tcode again afterward to start a session. In non-interactive contexts (CI, piped stdin), tcode instead exits with a "config not found" error that tells you to run tcode config.

tcode
tcode --web-only
tcode -p <profile>
tcode -c <container-name>
tcode -c <container-name> --container-runtime podman
tcode --no-container

Flags:

Flag	Description
`-p <profile>`	Load a specific config profile
`--web-only`	Create the new session in web-only mode. Existing sessions keep their stored mode.
`-V`, `--version`	Print version and git commit
`-c <name>`, `--container <name>`	Run bash commands inside a running Docker/Podman container. File tools remain on the host. See 02-configuration.md.
`--container-runtime <runtime>`	Container runtime CLI: `docker` (default) or `podman`. Requires `-c`.
`--no-container`	Force no container, even if `-c` or project config specifies one. Conflicts with `-c`.

`tcode config`

Interactively creates a new tcode config file at ~/.tcode/config.toml (or ~/.tcode/config-<profile>.toml with -p). Prompts for provider and then the credentials/endpoint fields relevant to that provider, and writes all other options (model, layout, subagent limits, browser server, search engine) as commented-out lines for you to uncomment later.

tcode config
tcode -p <profile> config

Flags:

Flag	Description
`-p <profile>`	Write to `~/.tcode/config-<profile>.toml` instead of the default file

Behavior:

Provider choices. The wizard menu offers six options: claude (Anthropic API key), claude-oauth (Claude Pro/Max subscription via OAuth), open-ai (OpenAI API key), open-ai-oauth (OpenAI Codex/ChatGPT Pro subscription via OAuth), open-router (OpenRouter API key), and bedrock (AWS Bedrock Claude via AWS credentials). The two OAuth providers (claude-oauth, open-ai-oauth) are distinct provider values: the wizard skips both the base URL and API-key prompts, writes the corresponding provider = "..." to the config file, and tells you to run the matching auth command (tcode claude-auth or tcode openai-auth, with -p <profile> as needed) afterward. At runtime, OAuth providers load tokens from disk using the selected profile and ignore both api_key in the config and the provider's environment variable. The Bedrock provider also skips base URL and API-key prompts; it uses AWS credential and region resolution, with optional aws_region and bedrock_endpoint fields available in the generated config.
Refuses to overwrite. If the target file already exists, the wizard errors with Config already exists at <path>. Edit it directly, or delete it first and re-run `tcode config`. To regenerate, delete the file first and re-run the wizard.
File permissions. On Unix the file is written with 0600 permissions via a temp-file + rename dance, so a crash or Ctrl-C mid-wizard does not leave a partial file at the real path.
Next-steps output. After writing, the wizard prints the config file's absolute path and points at 02-configuration.md for the full reference. For claude-oauth, it also prints a reminder to run the matching claude-auth command for the selected profile; for open-ai-oauth, a reminder to run the matching openai-auth command for the selected profile.

See 02-configuration.md for the wizard's first-run auto-launch behavior and the full list of options you can uncomment later.

`tcode attach`

Attaches to an existing session and resumes the conversation in the current tmux session. Must be run inside tmux. If --session is omitted, an interactive picker is shown. Existing sessions always use their stored mode; passing --web-only does not convert a normal session to web-only or a web-only session to normal.

The interactive picker lists sessions by last activity time. Press / to search conversation history across sessions. Search runs in the background and shows ranked snippet results with highlighted matches; the search index is checked in the background when the picker opens, so early results may be partial until that check finishes.

tcode attach
tcode --session <id> attach

Flags:

Flag	Description
`--session <id>`	Session ID to attach to. If omitted, an interactive picker is shown.

`tcode sessions`

Lists all sessions with their status (active or inactive), mode (normal or web-only), and description when available. Active sessions have a running server process.

Example output:

Sessions:
  abc123xy (active, web-only) Research notes
  def456uv (inactive, normal) Project refactor

tcode sessions

`tcode tree`

Opens a TUI tree view of the conversation's subagents and tool calls. Displays status, token usage, and hierarchical nesting. This pane is automatically shown in the right column when starting a new session.

tcode tree
tcode --session <id> tree

Flags:

Flag	Description
`--session <id>`	Session ID. If omitted, an interactive picker is shown.

`tcode permission`

Opens a TUI pane showing all tool permissions: pending requests, session grants, and project grants, grouped by tool and key. All known scopes and keys are always shown as a skeleton tree.

tcode permission
tcode --session <id> permission

Flags:

Flag	Description
`--session <id>`	Session ID. If omitted, an interactive picker is shown.

`tcode project-config-path`

Print the absolute path to the project config directory, where permissions.json and project config.toml are stored. The path is derived from the current working directory (hashed with SHA-256) and is stable across sessions.

tcode project-config-path

Example output:

/home/user/.tcode/projects/a1b2c3d4e5f6.../

No flags. The command only prints the path and does not create the directory.

`tcode browser`

Launches Chrome with the persistent profile. Use this to log in to services (e.g., Kagi for web search). The profile location depends on your Chrome installation; see Browser Setup. This is a standalone command and does not interact with the browser-server process. Press Ctrl+C to exit when done.

tcode browser

`tcode claude-auth`

Authenticates with Claude via OAuth. Intended for Claude Pro/Max subscribers who want to use their subscription credits via the API. Opens an authorization URL in the browser; the user pastes the returned code back into the terminal. On success, saves tokens to the profile-aware Claude token file: ~/.tcode/auth/claude_tokens.json with no profile, or ~/.tcode/auth/claude_tokens-<profile>.json when run with -p <profile>.

tcode claude-auth
tcode -p <profile> claude-auth

The same profile must be used later at runtime; tcode -p <profile> ... loads the matching claude_tokens-<profile>.json file and does not fall back to the default token file.

`tcode openai-auth`

Authenticates with OpenAI via OAuth. Intended for OpenAI Codex / ChatGPT Pro subscribers who want to use their subscription via the API. Starts a local HTTP server on port 1455 and opens the browser for login (PKCE authorization code flow). On success, saves tokens to the profile-aware OpenAI token file: ~/.tcode/auth/openai_tokens.json with no profile, or ~/.tcode/auth/openai_tokens-<profile>.json when run with -p <profile>.

tcode openai-auth
tcode -p <profile> openai-auth

The same profile must be used later at runtime; tcode -p <profile> ... loads the matching openai_tokens-<profile>.json file and does not fall back to the default token file.

`tcode remote`

Starts the web backend for browser access. The server binds to 127.0.0.1 by default and serves both /api/... routes and the single-page web UI from the same origin.

TCODE_REMOTE_PASSWORD=change-me tcode remote --port 8080

Open:

http://127.0.0.1:8080/

Use the same hostname consistently in the browser. The examples use 127.0.0.1; if you open localhost instead, keep using localhost for that browser session because cookies and same-origin checks are origin-specific. Log in with the shared secret passed at startup.

To select a config profile, pass -p at the top level:

TCODE_REMOTE_PASSWORD=change-me tcode -p <profile> remote --port 8080

You can pass the password on argv, but the environment variable is preferred because argv can leak through shell history or process listings:

tcode remote --port 8080 --password change-me

Flags:

Flag	Description
`--port <port>`	TCP port to bind. Required. `0` is rejected; choose a concrete port.
`--host <ip>`	IP address to bind. Defaults to `127.0.0.1`. Use `0.0.0.0` or `::` only when intentionally exposing the server beyond localhost.
`--password <secret>`	Shared secret for browser login. Prefer `TCODE_REMOTE_PASSWORD=<secret>` instead. If both are supplied, the explicit `--password` value is used.
`--allow-insecure-http`	Omit the `Secure` cookie attribute for direct plain-HTTP access. Use only for trusted local/private setups; prefer HTTPS or a trusted tunnel/proxy when exposed beyond localhost.

Relevant global flags:

Flag	Description
`-p <profile>`	Load `~/.tcode/config-<profile>.toml` instead of the default config.
`--web-only`	Create and expose only web-only sessions from this remote server. Accepted before or after `remote`; examples generally put it before the subcommand.
`-c <container>` / `--container <container>`	In normal remote sessions, run bash commands inside an existing Docker/Podman container. File tools still operate on the host.
`--container-runtime <runtime>`	Container runtime CLI for `-c/--container`: `docker` (default) or `podman`. Requires `-c/--container`.
`--no-container`	Force no container, even if `-c/--container` or project config specifies one. Conflicts with `-c/--container`.

--session <id> is not used by tcode remote; the web server lists and creates sessions through the browser UI.

Frontend serving:

Installed release binaries and install-from-source.sh builds embed the frontend in the tcode binary.
Development builds without --features tcode/bundled-frontend serve tcode-web/frontend/dist from the source checkout. If that directory is missing, /api/... can still work, but frontend browser routes return 404 until you run npm run build in tcode-web/frontend.

For setup walkthroughs, exposure guidance, and Docker deployment, see Remote Web UI.

Internal / Plumbing Commands

These commands are invoked internally by tcode -- from display keybindings, tmux popups, or the server process. They are not intended for direct use but are documented here for completeness.

`tcode serve`

Starts just the server process without any tmux integration. For a new empty session, --web-only initializes the session in web-only mode. If the session already has metadata or conversation state, the stored mode wins.

tcode --session <id> serve
tcode --session <id> --web-only serve

Flags:

Flag	Description
`--session <id>`	(required) Session ID
`--web-only`	Initialize a new empty session in web-only mode. Existing session metadata wins.

`tcode edit`

Opens a neovim editor for composing messages to send to the conversation.

tcode --session <id> edit
tcode --session <id> edit --conversation-id <cid>

Flags:

Flag	Description
`--session <id>`	(required) Session ID
`--conversation-id <id>`	Target a specific conversation (optional)

`tcode display`

Opens a neovim buffer that renders the conversation by tailing display.jsonl.

tcode --session <id> display

Flags:

Flag	Description
`--session <id>`	(required) Session ID

`tcode tool-call`

Opens a neovim buffer showing detailed output of a specific tool execution.

tcode --session <id> tool-call <tool-call-id>

Flags:

Flag	Description
`--session <id>`	(required) Session ID

Arguments:

Argument	Description
`<tool-call-id>`	(required) The ID of the tool call to inspect

`tcode cancel-tool`

Cancels a running tool call. The --session value can be a subagent session ID; the root session's socket is resolved automatically.

tcode --session <id> cancel-tool <tool-call-id>

Flags:

Flag	Description
`--session <id>`	(required) Session ID (can be a subagent session)

Arguments:

Argument	Description
`<tool-call-id>`	(required) The ID of the tool call to cancel

`tcode cancel-conversation`

Cancels an entire conversation, cascading cancellation to all running tools and child subagents. The --session value can be a subagent session ID; the root session's socket is resolved automatically.

tcode --session <id> cancel-conversation <conversation-id>

Flags:

Flag	Description
`--session <id>`	(required) Session ID (can be a subagent session)

Arguments:

Argument	Description
`<conversation-id>`	(required) The ID of the conversation to cancel

`tcode open-tool-call`

Opens a tool-call detail view in a new tmux window.

tcode --session <id> open-tool-call <tool-call-id>

Flags:

Flag	Description
`--session <id>`	(required) Session ID

Arguments:

Argument	Description
`<tool-call-id>`	(required) The ID of the tool call to open

`tcode open-subagent`

Opens a subagent's display and edit panes in a new tmux window (split layout).

tcode --session <id> open-subagent <conversation-id>

Flags:

Flag	Description
`--session <id>`	(required) Session ID

Arguments:

Argument	Description
`<conversation-id>`	(required) The conversation ID of the subagent to open

`tcode branch`

Clones a session's history strictly before a target user message into a brand-new, fully independent session and opens it in a new tmux tab (invoked by the gb keybinding in the display). The new session contains everything before that user message — the message itself is rewritten by typing a replacement in the new session — and is self-contained: subagent conversations, tool-call details, and media are copied, so the source session can be deleted without affecting the branch. The branch is opened with the same config profile as the source display.

tcode --session <id> branch <msg-id>

Flags:

Flag	Description
`--session <id>`	(required) Source session ID

Arguments:

Argument	Description
`<msg-id>`	(required) The display id of the user message to branch at

`tcode approve-next`

Opens pending tool approval requests one by one in tmux popups. This is the handler behind the Ctrl-p keybinding.

tcode --session <id> approve-next

Flags:

Flag	Description
`--session <id>`	(required) Session ID

`tcode approve`

Opens an approval or management dialog, designed to run inside tmux display-popup. Supports three modes: approve (default), management/revoke, and add-permission.

tcode --session <id> approve --tool <t> --key <k> --value <v>
tcode --session <id> approve --tool <t> --key <k> --value <v> --once-only
tcode --session <id> approve --tool <t> --key <k> --manage
tcode --session <id> approve --tool <t> --key <k> --add

Flags:

Flag	Description
`--session <id>`	(required) Session ID
`--tool <t>`	(required) Tool name
`--key <k>`	(required) Permission key
`--value <v>`	Permission value (required unless `--add`)
`--manage`	Open management/revoke mode instead of approve mode
`--add`	Add-permission mode with interactive value input (conflicts with `--manage`)
`--prompt <str>`	Human-readable prompt text (default: "")
`--request-id <uuid>`	Per-invocation request ID for AllowOnce targeting
`--preview-file-path <path>`	File path to preview (enables "[v] View in nvim")
`--once-only`	Only offer "Allow once" and "Deny" (no session/project caching)

Keybindings by mode:

Approve mode -- Phase 1 (menu):

Key	Action
`1`	Allow once
`2`	Allow for session
`3`	Allow for project
`4`	Deny (proceed to Phase 2 for optional reason)
`q` / `Esc`	Cancel

Approve mode -- Phase 2 (deny reason, only when 4 was chosen):

Key	Action
Printable chars	Append to reason input (500 char max)
`Backspace` (non-empty)	Delete last character
`Backspace` (empty)	Go back to Phase 1
`Enter`	Deny — empty / whitespace-only input denies without a reason
`Esc`	Go back to Phase 1
`Ctrl-C`	Cancel the popup

Management mode:

Key	Action
`r`	Revoke
`q` / `Esc`	Cancel

Add mode -- Phase 1 (type value):

Key	Action
Printable chars	Input value
`Backspace`	Delete character
`Enter`	Confirm value
`Esc` / `Ctrl-C`	Cancel

Add mode -- Phase 2 (choose scope):

Key	Action
`2`	Grant for session
`3`	Grant for project
`Backspace`	Go back to Phase 1
`q` / `Esc` / `Ctrl-C`	Cancel

FilesExpand file tree

03-commands.md

Latest commit

History

03-commands.md

File metadata and controls

tcode CLI Command Reference

User-Facing Commands

tcode

tcode config

tcode attach

tcode sessions

tcode tree

tcode permission

tcode project-config-path

tcode browser

tcode claude-auth

tcode openai-auth

tcode remote

Internal / Plumbing Commands

tcode serve

tcode edit

tcode display

tcode tool-call

tcode cancel-tool

tcode cancel-conversation

tcode open-tool-call

tcode open-subagent

tcode branch

tcode approve-next

tcode approve

`tcode`

`tcode config`

`tcode attach`

`tcode sessions`

`tcode tree`

`tcode permission`

`tcode project-config-path`

`tcode browser`

`tcode claude-auth`

`tcode openai-auth`

`tcode remote`

`tcode serve`

`tcode edit`

`tcode display`

`tcode tool-call`

`tcode cancel-tool`

`tcode cancel-conversation`

`tcode open-tool-call`

`tcode open-subagent`

`tcode branch`

`tcode approve-next`

`tcode approve`