tact

tact is a terminal interface for Nanocodex.

https://github.com/user-attachments/assets/5c634ae8-5c74-47c9-bb8c-9c18cb7fc97d

Execution environment

Tact does not sandbox agent commands by default. The agent can read and modify files and run processes with the same permissions as the user running Tact. For a containerized, credential- isolated setup, see the example development environment, which keeps real OpenAI credentials outside the development container while mounting the workspace and Tact state read-write.

Installation

The release installer supports x86-64 and ARM64 glibc-based Linux, as well as Intel and Apple Silicon Macs:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://tact.clab.by/install.sh | sh

It verifies the release checksum and installs tact in ~/.local/bin without sudo. Set TACT_INSTALL_DIR to another absolute directory if you prefer a different location.

You can also install the published crate with Cargo:

cargo install tact --locked

To build the current source instead:

git clone https://github.com/clabby/tact.git
cd tact
cargo install --locked --path bin/tact

Updates

Official release binaries can update themselves:

tact update

The updater verifies both the release checksum and signature before replacing a release-installer binary. If Cargo owns the installation, tact instead prints cargo install tact --locked so Cargo's records stay accurate, and builds declared through TACT_PACKAGE_MANAGER defer to the named package manager. Automatic update notifications are shown by every installation except development builds.

Packaging

Distribution packagers can declare the package manager that owns the installation at build time:

TACT_PACKAGE_MANAGER=nix cargo build --release

Such builds keep update notifications and the managed review interface, but tact update points at the owning package manager instead of replacing the binary in place. When building from a source archive without the git repository, the metadata reported by tact --version can be provided through the TACT_GIT_SHA, TACT_GIT_BRANCH, TACT_GIT_COMMIT_TIMESTAMP, and TACT_GIT_DIRTY environment variables.

Authentication

By default, tact uses the ChatGPT session stored by Codex in $CODEX_HOME/auth.json or ~/.codex/auth.json. If that file does not exist, it looks for OPENAI_API_KEY.

To sign in with a ChatGPT subscription:

tact auth login
tact auth status

tact auth logout removes the shared credential file, which also signs Codex out. If you want to require API-key authentication, pass the key through the environment:

export OPENAI_API_KEY="your-api-key"
tact --auth api-key

API keys are never written to tact's configuration or shown in status output.

Non-interactive use

For scripts and integrations, tact run submits one prompt and streams Nanocodex events as JSONL:

tact run "inspect the workspace"

Configuration

The configuration file is optional. Tact reads $TACT_HOME/config.toml, or ~/.tact/config.toml when TACT_HOME is unset. Select another file with --config PATH or TACT_CONFIG.

Use config show to discover every available field and inspect the complete effective configuration after file, environment, command-line, and default values have been applied:

tact config path
tact config show

The default effective configuration looks like this (paths depend on your environment):

[auth]
mode = "auto" # auto, chatgpt, or api-key
file = "/path/to/.codex/auth.json"

[agent]
workspace = "/path/to/workspace"
thinking = "medium" # low, medium, high, xhigh, or max
reasoning_mode = "standard" # standard or pro
fast_mode = false
max_subagents = 32
instructions = ""
append_instructions = ""
web_search = true
image_generation = true
websocket_url = ""
api_base_url = ""
completion_hook = ""

[mcp_servers]

[skills]
enabled = false
roots = []

[memory]
enabled = false

[subagents]
enabled = true
allow_luna = true

[theme]
mode = "auto" # auto, light, or dark

[theme.light]
text = "reset"
border = "dark-gray"
muted = "dark-gray"
accent = "blue"
code_text = "#262626"
code_background = "#EEEEEE"
thinking_low = "dark-gray"
thinking_medium = "#007878"
thinking_high = "#9A6700"
thinking_xhigh = "red"
thinking_max = "magenta"

[theme.dark]
text = "reset"
border = "dark-gray"
muted = "dark-gray"
accent = "blue"
code_text = "#D7D7D7"
code_background = "#262626"
thinking_low = "gray"
thinking_medium = "cyan"
thinking_high = "yellow"
thinking_xhigh = "red"
thinking_max = "magenta"

Set agent.completion_hook to a shell command to run after each conversation turn finishes. Tact runs the command in the configured workspace and ignores its output and exit status. Interactive sessions start the hook asynchronously so it does not block the UI; tact run waits for the hook before exiting.

The workspace defaults to the directory where tact starts. Relative paths in the configuration are resolved from the configuration file's directory; relative command-line paths are resolved from the current directory. Command-line options take precedence over environment variables, which take precedence over the file.

New sessions append concise built-in guidance for orchestrating related tool calls in code mode. When subagents are enabled, they also append guidance for delegation and multi-agent pipelines. Configured append_instructions follow that guidance.

Tact loads global instructions from AGENTS.override.md or AGENTS.md in CODEX_HOME, which defaults to ~/.codex, followed by project instructions from the Git repository root through the configured workspace.

The main agent options can also come from the environment. For example, --workspace, --thinking, and --resume correspond to TACT_WORKSPACE, TACT_THINKING, and TACT_RESUME. The prompt for tact run can be supplied through TACT_PROMPT. Run tact --help for the complete command-line reference.

The /subagents panel shows the current concurrency limit. Use - and + there to update it.

Use Reload config in the Actions menu after editing the file. Theme and UI changes apply immediately. Most agent settings apply when a session starts or is restored, while effort and fast mode can also be changed during a session. Workspace changes require restarting tact.

Themes

All theme options can be set directly under [theme] to apply to both palettes:

[theme]
mode = "auto" # auto, light, or dark
text = "reset"
border = "dark-gray"
muted = "dark-gray"
accent = "blue"
code_text = "#D7D7D7"
code_background = "#262626"
thinking_low = "gray"
thinking_medium = "cyan"
thinking_high = "yellow"
thinking_xhigh = "red"
thinking_max = "magenta"

Put any of the color options under [theme.light] or [theme.dark] to override that palette. Colors may be Ratatui names, indexed values such as 239, or RGB values such as "#AABBCC". Auto mode follows the operating-system theme while tact is running.

Custom Endpoints

Advanced deployments can set agent.websocket_url and agent.api_base_url, or use the --websocket-url and --api-base-url options. Leave them unset to use Nanocodex's defaults for the selected authentication method.

Features

Subagents

Subagents are enabled by default. Disable their tools and built-in delegation instructions with:

[subagents]
enabled = false

The reusable runtime and Nanocodex tool surface are published as the tact-subagents crate.

This setting applies when a session starts or is restored. Reloading the configuration does not change the tool surface of an already-running session. agent.max_subagents controls concurrency when the feature is enabled; setting it does not enable or disable subagents. See the subagent design for the tool, lifecycle, messaging, and authority contracts.

By default, agents may choose Luna for straightforward delegated work where latency matters more than reasoning capability. Require every subagent to use the session's selected model with:

[subagents]
allow_luna = false

Memory

Tact's bounded cross-session memory is disabled by default. Opt in explicitly:

[memory]
enabled = true

Local memory is global to the selected Tact configuration, not scoped to a workspace. Tact stores it in memory/v1.sqlite3 beside the selected config.toml. Agents access the selected local or remote backend only through explicit memory tool calls, and the corpus is never inserted into prompts automatically. For later user messages and in-flight steers, Tact adds a fixed, content-free checkpoint asking the agent to review the conversation and update memory when it finds a durable conclusion. See the global memory design for the tool contract, limits, privacy model, and evaluation criteria.

To share memory with a team, configure an authenticated remote backend. Each person uses a distinct namespace and may receive either writer or read-only credentials. Tact chooses exactly one backend for each runtime: remote inside a configured workspace root or a linked worktree from one, and local outside all configured roots.

[memory.remote]
endpoint = "https://memory.example.com/"
namespace = "alice"
bearer_token = "replace-with-a-secret-token"
workspace_roots = ["/pa