Truecode

Truecode is a terminal coding agent built on the Samyx ARC harness. It gives you an interactive TUI for working inside a local repository, dispatching worker agents, editing files, tracking diffs, rewinding work, using persistent project memory, and loading Claude-compatible plugins.

The package is intentionally local-first. Tool execution happens in the current working directory through the local filesystem and shell, not through the Firecracker sandbox service used by other parts of the Samyx monorepo.

Status

Truecode is an internal development package in this monorepo.

• Package name: @bluecopa/truecode
• Runtime: Node.js 22+
• Package manager: pnpm
• Main modes: interactive TUI and headless ARC runner
• Storage: ~/.truecode/projects/<sha256(cwd)[:12]>/
• Default provider: OpenRouter
• Default worker model: openrouter:z-ai/glm-5.1

Quick Start

From the monorepo:

pnpm install
pnpm --dir harness build
pnpm --dir truecode build

On first startup, if ~/.truecode/config.json does not exist, interactive Truecode prompts for an OpenRouter key, creates the config file, and starts with these defaults:

| Role | Default | |------|---------| | Orchestrator | openrouter:google/gemini-3.1-pro-preview | | Fast tier | openrouter:google/gemini-3.1-flash-lite-preview | | Worker | openrouter:z-ai/glm-5.1 |

For non-interactive setup, provide the key once through the process environment:

export OPENROUTER_API_KEY=...

Run the TUI in the repository you want Truecode to work on:

cd /path/to/project
node /path/to/samyx/truecode/bin/truecode.js

For development inside this monorepo, run Truecode from the repository root:

node truecode/bin/truecode.js

Resume the most recent saved session:

node /path/to/samyx/truecode/bin/truecode.js --resume

Resume a specific session by slug or ID prefix:

node /path/to/samyx/truecode/bin/truecode.js --resume rare-dawn

On resume, the TUI restores a compact preview of the last 10 chat turns from the saved snapshot. This is only for display; ARC still hydrates from the full session snapshot.

Configuration

Truecode uses ~/.truecode/config.json for the default provider key, model/provider choices, and runtime settings.

The config file is loaded from ~/.truecode/config.json by default. Set TRUECODE_CONFIG=/path/to/config.json to use a different file.

Example:

{
  "defaultProvider": "openrouter",
  "modelMap": {
    "fast": "openrouter:google/gemini-3.1-flash-lite-preview",
    "medium": "openrouter:google/gemini-3.1-pro-preview",
    "strong": "openrouter:google/gemini-3.1-pro-preview"
  },
  "orchestratorModel": "openrouter:google/gemini-3.1-pro-preview",
  "workerModel": "openrouter:z-ai/glm-5.1",
  "apiKeys": {
    "openrouter": "sk-or-..."
  },
  "workerModelMap": {
    "fast": "openrouter:google/gemini-3.1-flash-lite-preview",
    "medium": "openrouter:google/gemini-3.1-pro-preview",
    "strong": "openrouter:z-ai/glm-5.1"
  },
  "maxTurns": 12,
  "maxStepsPerWorker": 30,
  "reasoningEffort": "medium"
}

Process environment variables override config.json. Power users can export environment variables directly when they want temporary overrides.

Common variables:

| Variable | Purpose | |----------|---------| | TRUECODE_CONFIG | Optional path to a config JSON file. Defaults to ~/.truecode/config.json. | | LLM_PROVIDER | Default provider. Supported values include openrouter, openai, anthropic, google, and zai. Defaults to openrouter. | | TRUECODE_PROVIDER | Alias for LLM_PROVIDER. | | OPENROUTER_API_KEY | API key for OpenRouter. | | OPENROUTER_MODEL | Override the OpenRouter medium/strong model. Prefix is added automatically when missing. | | TRUECODE_MODEL_FAST | Override the fast model tier. | | TRUECODE_MODEL_MEDIUM | Override the medium model tier. | | TRUECODE_MODEL_STRONG | Override the strong model tier. | | TRUECODE_ORCHESTRATOR_MODEL | Override the exact orchestrator model. | | OPENAI_API_KEY | API key for OpenAI. | | ANTHROPIC_API_KEY | API key for Anthropic. | | GOOGLE_GENERATIVE_AI_API_KEY | API key for Google Gemini. | | ZAI_API_KEY | API key for Z.ai. | | WORKER_MODEL | Override the default worker model. Defaults to the provider-local strong model, except OpenRouter which defaults to openrouter:z-ai/glm-5.1. | | TRUECODE_WORKER_MODEL | Alias for WORKER_MODEL. | | TRUECODE_WORKER_MODEL_FAST | Override the fast worker model tier. | | TRUECODE_WORKER_MODEL_MEDIUM | Override the medium worker model tier. | | TRUECODE_WORKER_MODEL_STRONG | Override the strong worker model tier. | | FAST_MODEL | Legacy override for the fast worker tier. | | ORG_WORKER_MODEL | Legacy headless orchestrator tier: fast, medium, or strong. Defaults to strong. | | TRUECODE_ORCHESTRATOR_TIER | Alias for ORG_WORKER_MODEL. | | TRUECODE_MAX_TURNS | Override max orchestrator turns. | | TRUECODE_MAX_STEPS_PER_WORKER | Override max steps per untiered worker. | | REASONING_EFFORT | OpenAI/OpenRouter reasoning effort option. | | TRUECODE_REASONING_EFFORT | Alias for REASONING_EFFORT. | | HARNESS_PROFILE | Set to 1 to enable ARC telemetry summaries. | | TRUECODE_PLUGIN_LOG | Set to 1 in headless mode to print plugin loading logs. |

Provider model tier defaults are defined in src/config/model-provider.ts.

For Gemini through OpenRouter, use OpenRouter as the provider and put the Gemini model under the openrouter: namespace:

export LLM_PROVIDER=openrouter
export OPENROUTER_MODEL=google/gemini-3.1-pro-preview
export TRUECODE_MODEL_FAST=openrouter:google/gemini-3.1-flash-lite-preview
export WORKER_MODEL=openrouter:z-ai/glm-5.1

To keep OpenRouter Gemini as the orchestrator and use direct ZAI for workers, keep defaultProvider as openrouter and prefix worker models with zai::

{
  "defaultProvider": "openrouter",
  "modelMap": {
    "fast": "openrouter:google/gemini-3.1-flash-lite-preview",
    "medium": "openrouter:google/gemini-3.1-pro-preview",
    "strong": "openrouter:google/gemini-3.1-pro-preview"
  },
  "orchestratorModel": "openrouter:google/gemini-3.1-pro-preview",
  "workerModel": "zai:glm-5.1",
  "apiKeys": {
    "openrouter": "sk-or-...",
    "zai": "..."
  },
  "workerModelMap": {
    "fast": "zai:GLM-5-Turbo",
    "medium": "zai:glm-5.1",
    "strong": "zai:glm-5.1"
  }
}

For first-run setup without an existing config, export both keys:

export OPENROUTER_API_KEY=sk-or-...
export ZAI_API_KEY=...
truecode

Interactive TUI

Start Truecode and enter a natural-language task:

Welcome to truecode. Type /help for commands, or enter a task.

The TUI shows:

• User prompts and assistant responses
• Worker dispatches and public rationale as append-only transcript entries
• File diffs for writes and edits
• A live worker activity strip above the prompt showing the current tool and compact tool counts
• A live model-call strip above the prompt showing active orchestrator/worker LLM calls and elapsed time
• System events such as memory reads, memory writes, plugin use, and errors
• A footer with orchestrator model, worker model, token counts, git branch, session slug, todo progress, and profiling state

The footer symbols are:

| Symbol | Meaning | |--------|---------| | ⬡ | Orchestrator model | | △ | Worker model | | ⎇ | Current git branch or detached commit label | | ◈ | Session slug | | ☑ | Completed todos / total todos |

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl+C | Stop the current task. When idle, quit Truecode. | | Esc | Clear prompt text. With an empty prompt during a task, interrupt the current turn and allow steering. | | Up with an empty prompt | Open the rewind overlay. | | Ctrl+D | Open the diff overlay. | | Ctrl+T | Open the ARC trace overlay. | | Ctrl+L | Clear the chat view. | | Ctrl+V | Attach a clipboard image when one is available. |

Slash commands autocomplete from the input box.

Slash Commands

| Command | Description | |---------|-------------| | /help | Show available commands and shortcuts. Alias: /?. | | /clear | Clear the chat view. | | /quit | Exit Truecode. Aliases: /q, /exit. | | /model | Show or set the exact orchestrator model ID. | | /mode | Switch model tier: fast, medium, or strong. | | /budget | Show or set maxTurns and maxStepsPerWorker. Example: /budget turns=16 steps=40. | | /dispatch | Show current or recent worker dispatches. Alias: /workers. | | /mcp | List connected MCP servers and their tools. | | /plugin | Show plugin status. Alias: /plugins. | | /plugin marketplaces | List Claude marketplaces discovered under ~/.claude/plugins/marketplaces. | | /plugin install <path> | Install a local Claude-compatible plugin into ~/.truecode/plugins. | | /plugin install claude:<marketplace>/<plugin> | Install from a local Claude marketplace entry. | | /diff | Open the diff overlay. Inline edit diffs are rendered in chat; overlay population is still being completed. | | /trace | Show the ARC event trace log. | | /history | Show task history for this session. | | /sessions | List saved sessions. | | /rewind status | Show recorded file changes for the selected/latest task. | | /rewind --force | Revert recorded file changes for the latest task, even if files changed after Truecode edited them. | | /branch | Show the current git branch. | | /branch <name> | Create and switch to a new git branch. | | /config | Show current runtime configuration. | | /profile | Show harness profiling stats. Alias: /prof. Requires HARNESS_PROFILE=1. | | /todos | Open the session todo overlay. Alias: /todo. | | /todos status | Print the current session todo list. | | /todos clear | Clear the current session todo list. | | /theme | Placeholder command for theme selection. | | /btw <text> | Records visible context in the chat. Full context injection is still a follow-up. |

Agent Design

Truecode uses the ARC loop from @bluecopa/harness.

User prompt
  -> Orchestrator model
       -> dispatches workers
            -> workers use tools
            -> workers return summaries, artifacts, and status
       -> orchestrator finalizes or asks for more work
  -> TUI renders the final answer

The orchestrator does not directly read files, mutate files, access memory, or manage todos. It decides when to dispatch workers. Workers receive the file, shell, memory, todo, plugin, MCP, and web tools that are available for the current runtime.

This split keeps the orchestrator cheap and focused while allowing workers to run code, inspect files, and make edits.

Worker Budgets

Worker step budgets are centralized in the harness:

| Tier | Initial steps | |------|---------------| | untiered/default | 30 | | fast | 12 | | medium | 24 | | strong | 40 |

Workers can request more steps. Each extension grants 15 more steps, capped at 60 total steps.

The TUI /budget command controls the fallback maxStepsPerWorker used for untiered dispatches.

Tools Available to Workers

Core tools:

| Tool | Purpose | |------|---------| | Bash | Run a shell command. | | ReadOnlyBash | Run inspection commands that should not mutate files. | | StartCommand | Start a long-running command asynchronously when provider support exists. | | CheckCommand | Poll a command started with StartCommand. | | CancelCommand | Stop a command started with StartCommand. | | Read | Read a file. | | Write | Create or overwrite a file. | | Edit | Replace exact text in a file. | | TextEditor | Claude-style structured file viewer/editor. | | Glob | Find files by glob. | | Grep | Search file contents. | | WebFetch | Fetch URL content when a provider implementation is configured. | | WebSearch | Search the web when a provider implementation is configured. | | Show | Show content to the user. |

Truecode tools:

| Tool | Purpose | |------|---------| | Memory_Read | Read persistent project memory. | | Memory_Write | Append to persistent project memory. | | TodoRead | Read the current session todo list. | | TodoWrite | Replace the current session todo list. | | Plugin_ListComponents | List installed plugin commands, skills, and agents. | | Plugin_ReadComponent | Read exact instructions for a plugin component. |

MCP tools are exposed as:

mcp__<serverName>__<toolName>

Persistent State

Truecode stores project-scoped state in ~/.truecode/projects/<hash>/, where <hash> is the first 12 characters of sha256(cwd).

~/.truecode/
  config.json
  .mcp.json
  hooks.json
  plugins/
  skills/
  projects/
    <project-hash>/
      memory.md
      mem/
        index/
        notes/
        transcripts/
        artifacts.json
      sessions/
        slugs.json
        <session-id>/
          meta.json
          snapshot.json
          rewind.json
          todos.json

Memory

Memory is project-wide and persists across sessions. Workers can read it with Memory_Read and append to it with Memory_Write.

When the user asks Truecode to remember something, the orchestrator should dispatch a worker to write to project memory. Repository instruction files such as CLAUDE.md or .cursorrules are separate repo-config files, not Truecode memory.

Todos

Todos are session-scoped. Workers update them through TodoWrite, which replaces the full current list. The footer shows completed todos out of total todos, todo writes append a short summary to the transcript, /todos opens the current list overlay, and /todos status prints the list.

Sessions

Each TUI or headless run gets a UUID and a human-readable slug such as rare-dawn. Snapshots are saved through the ARC session store so runs can be resumed by slug or ID prefix.

When a TUI session is resumed, Truecode appends a compact chat preview from the saved orchestrator conversation. The preview shows the last 10 user turns and their assistant replies, skips internal tool/result chatter, and truncates very long entries.

Rewind

Truecode records a checkpoint at the start of each task:

• User message
• ARC session snapshot
• Current todos
• File mutations recorded from Write, Edit, TextEditor, and git-aware Bash snapshots

Open rewind with Up on an empty prompt. Choose a prior user message and then choose:

• conversation only
• conversation plus file changes

/rewind status shows recorded changes for the latest task. /rewind --force reverts latest-task changes even if a file has changed after Truecode edited it.

Rewind only tracks text files small enough to snapshot. Large files and binary files are skipped.

Diffs

Successful file mutations return unified diffs. The TUI renders edit diffs inline in the chat view.

Diff rendering includes syntax highlighting for code blocks and full-line background styling for added and removed lines. Additions use a blue background and removals use a red background.

Plugins

Truecode supports Claude-compatible plugin directories installed under:

~/.truecode/plugins/<plugin-name>/

Each plugin must include:

.claude-plugin/plugin.json

Supported plugin components:

| Component | Location | Behavior | |-----------|----------|----------| | Commands | commands/**/*.md or manifest-declared paths | Registered as slash commands. | | Skills | skills/*/SKILL.md or manifest-declared paths | Available to workers through plugin component tools. | | Agents | agents/**/*.md or manifest-declared paths | Available to workers through plugin component tools. | | MCP servers | mcpServers in plugin.json | Connected and exposed as worker tools. | | Hooks | hooks/hooks.json or manifest-declared paths | Loaded for status. Hook execution is not currently wired into tool calls. |

Install a local plugin:

/plugin install /path/to/plugin

Replace an installed plugin:

/plugin install /path/to/plugin --force

List plugin status:

/plugin

When a worker reads a plugin command, skill, or agent, the TUI adds a system line such as:

Using skill: plan from compound-engineering.

Claude Marketplaces

Truecode can read local Claude marketplace metadata from:

~/.claude/plugins/marketplaces/<marketplace>/.claude-plugin/marketplace.json

List available marketplace plugins:

/plugin marketplaces

Install one:

/plugin install claude:<marketplace>/<plugin>

Marketplace entries must point to local plugin source paths. HTTP sources are intentionally ignored.

Skills

Standalone Truecode skills are discovered from:

~/.truecode/skills/<name>/SKILL.md
<project>/.truecode/skills/<name>/SKILL.md

Project skills override global skills with the same name. These standalone skills are registered as slash commands that render the skill body into chat. Claude-compatible plugin skills are separate and are exposed to workers through Plugin_ListComponents and Plugin_ReadComponent.

Skills must include markdown content and may include YAML frontmatter:

---
name: example-skill
description: What this skill helps with
---

Skill instructions go here.

MCP

Trusted global MCP config is loaded from:

~/.truecode/.mcp.json

Project-local .mcp.json files are not loaded. This is deliberate: cloned repositories should not be able to spawn arbitrary MCP processes by default.

Example stdio server:

{
  "mcpServers": {
    "example": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "EXAMPLE_TOKEN": "${EXAMPLE_TOKEN}"
      }
    }
  }
}

Example HTTP server:

{
  "mcpServers": {
    "remote": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}

Use /mcp to see connected servers and tool names.

Hooks

Truecode loads global hooks from:

~/.truecode/hooks.json

Project-local hooks are not loaded for the same reason as project-local MCP configs: hook commands execute locally. Hook environment variables are sanitized to remove names containing KEY, SECRET, TOKEN, or PASSWORD.

Current limitation: hooks are loaded and shown in plugin status, but hook execution is not wired into the tool execution path yet.

Headless Mode

Headless mode runs the same ARC agent without the TUI. It is useful for tests, Terminal-Bench style workloads, and scripted tasks.

From a target repository:

cd /path/to/project
node /path/to/samyx/truecode/dist/headless.js "summarize this repository"

For package development:

pnpm --dir truecode headless -- "summarize this repository"

Headless mode prints:

• selected orchestrator and worker models
• session slug and UUID
• ARC turns and dispatches
• worker progress
• trace events
• final output
• profiling summary when HARNESS_PROFILE=1

Headless mode initializes plugins and includes MCP/plugin tools in the worker registry.

If headless mode runs without a TTY and ~/.truecode/config.json is missing, it exits with a setup error instead of prompting. Set OPENROUTER_API_KEY once or run interactive Truecode once to create ~/.truecode/config.json.

Profiling

Set:

export HARNESS_PROFILE=1

The TUI prints a task profile after each task and /profile prints the session profile. The profile summarizes ARC spans and metrics, including orchestrator model time, worker model time, dispatch time, tool calls, and tool durations.

Development

Run tests:

pnpm --dir truecode test

Run a focused test:

pnpm --dir truecode test -- output-filter.test.ts

Type-check:

pnpm --dir truecode typecheck

Build:

pnpm --dir truecode build

Common full verification:

pnpm --dir harness build
pnpm --dir truecode typecheck
pnpm --dir truecode test
pnpm --dir truecode build

Source Map

| Path | Responsibility | |------|----------------| | src/cli.ts | Interactive TUI entry point, model/provider setup, persistent stores, session setup. | | src/headless.ts | Non-TUI ARC runner. | | src/tui/truecode-tui.ts | Main TUI lifecycle, keybindings, ARC bridge callbacks, overlays, tasks, rewind, todos. | | src/tui/components/ | Chat view, input bar, overlays, worker activity strip, model-call strip, footer/status rendering. | | src/commands/ | Slash command registry and built-in commands. | | src/tools/agent-tools.ts | Worker tool registry, memory tools, todo tools, plugin tools. | | src/adapters/tool-provider.ts | Local filesystem/shell ToolProvider adapter. | | src/plugins/ | Claude-compatible plugin loading, skill discovery, MCP connection, plugin command registration. | | src/prompts/ | Orchestrator and worker prompt suffixes plus project instruction loading. | | src/rewind/ | Task checkpoints, file mutation tracking, git workspace snapshots. | | src/todos/ | File-backed session todo storage and rendering. | | src/stores/ | File-backed scratchpad, session, and vector index stores. | | src/observability/ | Harness telemetry summaries. | | tests/ | Vitest coverage for tools, plugins, rendering, rewind snapshots, todos, and command behavior. |

Security Model

Truecode runs locally with access to your working directory and shell.

Important guardrails:

• MCP config is loaded only from ~/.truecode/.mcp.json.
• Hooks config is loaded only from ~/.truecode/hooks.json.
• Plugin installs copy from local paths or local Claude marketplace entries.
• Plugin installer refuses HTTP marketplace sources.
• /branch and /rewind use execFile argument arrays rather than interpolated shell strings.
• Hook environment variables are sanitized.
• Tool output from normal successful shell reads is not printed into chat unless it is an error or an explicit Show.

Truecode does not sandbox local tool execution. Treat plugins, MCP servers, and hooks as trusted code.

Current Limitations

• /btw currently adds a visible chat marker but does not inject durable context into the next ARC task.
• /theme is a placeholder command.
• /diff opens the overlay, but task-level overlay population is not fully wired. Inline edit diffs are rendered in chat.
• Hook execution is not yet wired into worker tool execution.
• The TUI is optimized for local interactive use. Headless mode has less UI state inspection.
• Rewind snapshots skip binary files and text files over the snapshot size limit.