@bluecopa/truecode

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.