Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Temicide/thcode/llms.txt

Use this file to discover all available pages before exploring further.

thcode operates in one of two Work Modes at all times: Plan and Build. These modes are not pipeline stages — they are independently selectable dimensions of session state. You can enter either mode directly, switch freely between them mid-session, and the currently active mode is always visible in the terminal UI. Work Mode is orthogonal to Permission Profile: neither implies the other, and both must be treated as separate UI state.

​
What makes Plan mode different

Plan mode enforces a structural read-only boundary. This is not a policy layer that a sufficiently permissive Permission Profile can override — it is a hard architectural rule evaluated before the permission engine runs. Even full-access in Plan mode cannot authorize a mutation. The ToolRegistry.resolveForMode() method refuses to surface mutating tools to the model when mode is plan, and evaluatePermission() short-circuits to deny before reaching any profile logic. 
// From permissions/policy.ts
// 1. Structural read-only boundary of Plan Mode (ADR 0013). Non-negotiable.
if (state.mode === 'plan' && action.mutating) {
  return {
    outcome: 'deny',
    reason: 'plan-mode-is-read-only',
  };
}
The PlanModeToolRefusedError is raised at the registry level when the model proposes a mutating tool name while in Plan mode, before the permission engine is ever consulted. 
// From tools/registry.ts
export class PlanModeToolRefusedError extends Error {
  constructor(tool: string) {
    super(`Tool "${tool}" is mutating and cannot run in Plan Mode (read-only).`);
    this.name = 'PlanModeToolRefusedError';
  }
}

​
Session defaults

Every new interactive session starts in Build mode with the Manual Permission Profile. This is the NEW_SESSION_DEFAULT constant from permissions/types.ts: 
export const NEW_SESSION_DEFAULT: { mode: WorkMode; profile: PermissionProfile } = {
  mode: 'build',
  profile: 'manual',
};

​
Switching modes

Keyboard shortcut

Press Shift+Tab to cycle directly between Plan and Build. Plain Tab is reserved for /command and @file completion.

Slash commands

Type /plan to enter Plan mode or /build to enter Build mode explicitly from the command line.

​
What Plan mode can do

Plan mode allows all non-mutating operations. The model can fully analyze a codebase, surface intended changes, and report any preflight issues before a single byte is written.
1

Read files

read_file is non-mutating and available in Plan mode. The model can read any file within the workspace boundary.
2

List directories

list_dir is non-mutating. The model can explore the workspace directory tree freely.
3

Search

search is non-mutating. Grep-style content search and file discovery are available.
4

Show a plan

The model can emit a structured summary of intended files, commands, risks, and verification criteria — without executing any of them.
5

Non-mutating dependency preflight

The model can run non-mutating toolchain discovery to check whether required dependencies are present before proposing build steps.

​
What Plan mode cannot do

Any action whose mutating flag is true in the Permission Matrix is blocked unconditionally while in Plan mode, regardless of Permission Profile.
Plan mode cannot write files, delete files, or run commands. These are mutating action classes and are structurally denied — not just policy-denied. No profile or developer override can change this while Plan mode is active. Note that transfer is non-mutating and is not blocked by Plan mode, but it is sensitive and will always require approval.

​
Action class reference

The Permission Matrix defines a fixed registry of action classes with static attributes. A class absent from this registry is treated as unknown and denied. The table below reflects PERMISSION_MATRIX_VERSION = 1 from permissions/matrix.ts.
Action ClassMutatingSensitiveRiskRequires Enforcement CapabilityAvailable in Plan
read_fileNoNolow—✅ Yes
list_dirNoNolow—✅ Yes
searchNoNolow—✅ Yes
write_fileYesNomediumfilesystem-write❌ No
deleteYesNohighfilesystem-delete❌ No
run_commandYesNohighcommand-exec❌ No
transferNoYeshighnetwork-transfer⚠️ Ask (sensitive)
transfer is marked non-mutating but sensitive, and carries a high risk rating. It is not structurally blocked in Plan mode (it is not mutating), but sensitive actions always require approval — evaluatePermission() returns ask for any sensitive action unless full-access holds the explicit sensitiveOverride flag. See Permission Profiles.

​
Build mode

Build mode lifts the structural read-only restriction. Mutating tools become available to the model, and whether any particular mutating action executes automatically or asks for approval is governed entirely by the active Permission Profile. Build mode combined with full-access means no per-action prompts for non-sensitive operations inside declared workspace boundaries.
Switching from Plan to Build does not consume or require a plan. You can enter Build mode directly at session start, and you can switch back to Plan at any time to inspect the workspace without risk of mutation.

Build docs developers (and LLMs) love

Get started for freeTalk to us