Sachin Koli

HooCodeStart here

Modes

A mode swaps the system prompt hoocode runs under, so the same session can be steered between answering questions, designing a change, and making it.

A mode prompt is instructions; what actually blocks a tool call is the mode’s entry in hoo-config.json. The two are meant to agree, and the shipped defaults below make them agree for the read-only modes — but if you write a custom mode prompt that forbids something, add the matching policy or nothing enforces it.

The active mode is build unless configured otherwise.

Switching

/mode ask       # read-only Q&A
/mode plan      # explore and design, no source edits
/mode build     # careful implementation (default)
/mode debug     # root-cause analysis, no file modifications
/plan           # shorthand for /mode plan

The active mode persists in hoo-config.json under active_mode. Switching back to build clears the key rather than writing the default.

The four built-in modes

Mode For Tells the model to
ask Questions about a codebase Read, SearchCodebase, trace, and explain, citing paths and line numbers; decline edits and suggest /mode build
plan Designing a change before making it Explore, ask blocking questions with ask_options, then write a plan with Goal / Files to modify / New files / Tests / Verification
build Implementing Read before editing, one verified change at a time, name what an irreversible operation destroys before running it, never commit or push unasked, run tests after each unit of work
debug Finding a root cause Gather evidence, reproduce, trace the call path, state the root cause in one sentence, describe the fix without applying it

What each mode actually permits

The mode prompts above say what the model should do; these are the shipped defaults in hoo-config.json that decide what it can do. Edit them per mode, globally in ~/.hoocode/hoo-config.json or per project in ./.hoocode/hoo-config.json.

Mode auto_allow (runs without a prompt) Hard policy
ask read denied_tools: [edit, write]
plan read, write allowed_write_paths: [.hoocode/plans/*, .hoocode/plan.md]
build read none — every bash/edit/write is gated
debug read, bash denied_tools: [edit, write]
  • denied_tools is hard enforcement: it applies with or without a UI, so it holds in --print runs too.
  • allowed_write_paths covers both edit and write, and is checked before auto_allow — which is what confines plan mode to its plan file even though write is auto-allowed there. It is currently only applied in interactive sessions.
  • bash is not restricted by tool policy in any shipped mode. In ask and debug the prompt is what keeps it read-only; if you need that enforced, set allowed_bash_commands (a hard-enforced regex allowlist) for the mode.

The planning workflow

Plan mode writes to .hoocode/plans/<session-id>.md. Each session gets its own plan file, so two sessions in one project do not overwrite each other. (.hoocode/plan.md, the older single-file location, is still read as a fallback.)

Once a plan exists:

/grill [me|plan]   # stress-test it before committing to it
/approve           # accept it and switch to build mode to execute
/goal [--max-turns N] [objective]

/approve switches to build. /goal runs autonomously toward an objective — if you do not type one, it takes the plan’s Goal section, and the plan’s Verification section becomes the completion condition either way. Cap the run with --max-turns.

/grill is worth the round trip when a plan carries real risk; it argues against the plan rather than refining it.

Custom modes

A mode is a directory containing system.md. hoocode resolves a mode name against these locations, first match winning:

  1. ./.hoocode/modes/<name>/system.md (project)
  2. ~/.hoocode/modes/<name>/system.md (user)
  3. Directories passed with --mode-path
  4. The built-in prompt, for the four names above

The built-in prompt is the same text /init scaffolds into a project: both come from templates/modes/<name>/system.md. There is no second copy, so a project that ran /init and one that did not behave identically until you edit the file.

So ./.hoocode/modes/build/system.md overrides the shipped build prompt for one project, and ./.hoocode/modes/review/system.md adds a review mode that /mode review will find.

In a plan-mode template, {{PLAN_PATH}} is substituted with the session’s plan file path, relative to the working directory.

.hoocode/
└── modes/
    └── review/
        └── system.md

Start one with hoocode --mode review, or switch mid-session with /mode review.