Using HooCode

This page collects day-to-day usage details that do not fit on the quickstart page.

Interactive Mode

The interface has four main areas:

• Startup header - shortcuts, loaded context files, prompt templates, skills, and extensions
• Messages - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
• Editor - where you type; border color indicates the current thinking level
• Footer - working directory, session name, token/cache usage, cost, context usage, and current model

The editor can be replaced temporarily by built-in UI such as /settings or by custom extension UI.

Editor Features

See Keybindings for all shortcuts and customization.

Slash Commands

Type / in the editor to open command completion. Extensions can register custom commands, skills are available as /skill:name, and prompt templates expand via /templatename.

Modes and planning

See Modes for what each mode changes.

Plugins and extensibility

See Plugins for the marketplace and trust model.

Canvas and scheduling

Message Queue

You can submit messages while the agent is still working:

• Enter queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
• Alt+Enter queues a follow-up message, delivered after the agent finishes all work.
• Escape aborts and restores queued messages to the editor.
• Alt+Up retrieves queued messages back to the editor.

On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in Terminal setup if you want hoocode to receive the shortcut.

Configure delivery in Settings with steeringMode and followUpMode.

Sessions

Sessions are saved automatically to ~/.hoocode/sessions/, organized by working directory.

hoocode -c                  # Continue most recent session
hoocode -r                  # Browse and select a session
hoocode --no-session        # Ephemeral mode; do not save
hoocode --session <path|id> # Use a specific session file or session ID
hoocode --fork <path|id>    # Fork a session into a new session file

Useful session commands:

• /session shows the current session file and ID.
• /tree navigates the in-file session tree and can summarize abandoned branches.
• /fork creates a new session from an earlier user message.
• /clone duplicates the current active branch into a new session file.
• /compact summarizes older messages to free context.

See Sessions and Compaction for details.

Context Files

HooCode loads AGENTS.md or CLAUDE.md at startup from, least specific first:

• ~/.agents/AGENTS.md — the cross-vendor user scope, shared with other agent tools
• ~/.hoocode/AGENTS.md — hoocode’s own global instructions, which win on conflict
• parent directories, walking up from the current working directory
• the current directory

Both user scopes are read additively: neither shadows the other, so an existing ~/.hoocode file keeps working when you add a ~/.agents one.

Use context files for project conventions, commands, safety rules, and preferences. Disable loading with --no-context-files or -nc.

Context files are re-sent on every request, so their size is a recurring cost. HooCode warns when one file grows past ~2k tokens, truncates it past ~10k, and warns again when the set as a whole passes ~6k — trimming the least specific scope first past ~16k. The startup listing shows the running total.

Long or conditional guidance belongs in a skill instead: skills load on demand, context files load always.

Learning rules from your sessions

/learn reads recent session transcripts for this directory, and reports what repeated:

• Directives you restated across sessions — candidate rules, with the count that justifies them. An item marked restated is already covered by a rule that is not working and wants rewriting, not duplicating.
• Failures you resolved — a command that failed, then later succeeded unchanged, with the work in between.
• Repeated tool sequences — candidate skills. Only procedures qualify: a sequence has to chain at least two distinct doing-commands (test then commit, build then publish). The edit/test rhythm is one command and every rotation of itself, so it is not reported.

It then proposes edits to the repo AGENTS.md, to ~/.agents/AGENTS.md for habits that travel with you, or as a new skill. Nothing is written without the usual edit approval. Because it reads transcripts from disk rather than the live conversation, it still works after the session has been compacted.

/learn stats reports what became of past proposals: how many were shown, and what share of the directive proposals you actually wrote down. It reads the history file rather than re-mining sessions, so it is instant.

Read the number carefully. Adoption is a proxy for usefulness, not ground truth — a proposal you correctly rejected as not durable counts against it exactly like a junk one. Near zero means the extractor is proposing the wrong things; near 100% means the bar is too low and everything is getting through. The trend matters more than the value, and it is the fastest way to tell whether a change to learnMinRepeats helped.

/learn remembers what it has already shown you, per directory. An item comes back only once it recurs after it was last put in front of you — so a rule you accepted is not re-proposed, and one you passed on does not reappear every run unchanged. Something you keep saying anyway will return, which is the point: that is the case where the existing rule is not working. Run /learn all to ignore that memory and re-propose everything in the window.

An item shown before that still is not written down anywhere is flagged as previously declined, so it is proposed tentatively rather than pressed a second time. That inference reads context files and skills alike, so a proposal you routed to ~/.agents/AGENTS.md or turned into a skill both count as adopted.

When a directive is already covered by a skill and you keep asking for it by hand, it comes back marked has-skill rather than as a new rule. That is a triggering problem, not a missing rule: the skill’s description frontmatter probably does not describe the situation you were in, so sharpening it is the fix rather than writing a rule that duplicates the skill.

The five thresholds are editable from /settings under Learning. /learn settings prints the same values as text, along with where sessions are read from, how many were found, and the two files you can set them in by hand — the user ~/.hoocode/settings.json and the project .hoocode/settings.json. See settings for what each one does.

Sessions are read from ~/.hoocode/sessions/<encoded-cwd>/, the directory hoocode writes this project’s transcripts into. If a run reports nothing, it names that directory, how many transcripts it holds, and why each was passed over — out of the age window, over the session cap, or recorded under a different working directory. Those are the three reasons a directory full of history still mines to nothing, and each has a different fix: widen learnMaxAgeDays, raise learnMaxSessions, or check that you are running from the same path the sessions were recorded under.

System Prompt Files

Replace the default system prompt with:

• .hoocode/SYSTEM.md for a project
• ~/.hoocode/SYSTEM.md globally

Append to the default prompt without replacing it with APPEND_SYSTEM.md in either location.

Exporting and Sharing Sessions

Use /export [file] to write a session to HTML.

Use /share to upload a private GitHub gist with a shareable HTML link.

If you use hoocode for open source work and want to publish sessions for model, prompt, tool, and evaluation research, see badlogic/pi-share-hf. It publishes sessions to Hugging Face datasets.

CLI Reference

hoocode [options] [@files...] [messages...]

Package Commands

hoocode install <source> [-l]     # Install package, -l for project-local
hoocode remove <source> [-l]      # Remove package
hoocode uninstall <source> [-l]   # Alias for remove
hoocode update [source|self|hoocode]   # Update hoocode and packages; skips pinned packages
hoocode update --extensions       # Update packages only
hoocode update --self             # Update hoocode only
hoocode update --extension <src>  # Update one package
hoocode list                      # List installed packages
hoocode config                    # Enable/disable package resources

See HooCode Packages for package sources and security notes.

Modes

In print mode, hoocode also reads piped stdin and merges it into the initial prompt:

cat README.md | hoocode -p "Summarize this text"

Model Options

Session Options

Tool Options

Built-in tools: read, bash, edit, write, SearchCodebase.

Optional tool bundles

Off by default unless noted; each adds a capability rather than a single tool.

Subagents

See Subagent delegation.

Resource Options

Combine --no-* with explicit flags to load exactly what you need, ignoring settings. Example:

hoocode --no-extensions -e ./my-extension.ts

Other Options

Light mode

--light (or the light setting, editable in /settings under Context) trims the session to the smallest useful fixed per-turn surface, for small or local models that waste context on harness boilerplate:

• Only read, write, edit, and bash, with short descriptions and stripped parameter schemas. bash subsumes SearchCodebase — discovery happens via the shell.
• A terse replacement system prompt.
• No subagents, TodoWrite, skills, context files, mode appendix, or the self-documentation section.

--print-token-surface reports what that surface actually costs.

File Arguments

Prefix files with @ to include them in the message:

hoocode @prompt.md "Answer this"
hoocode -p @screenshot.png "What's in this image?"
hoocode @code.ts @test.ts "Review these files"

Examples

# Interactive with initial prompt
hoocode "List all .ts files in src/"

# Non-interactive
hoocode -p "Summarize this codebase"

# Non-interactive with piped stdin
cat README.md | hoocode -p "Summarize this text"

# Different model
hoocode --provider openai --model gpt-4o "Help me refactor"

# Model with provider prefix
hoocode --model openai/gpt-4o "Help me refactor"

# Model with thinking level shorthand
hoocode --model sonnet:high "Solve this complex problem"

# Limit model cycling
hoocode --models "claude-*,gpt-4o"

# Read-only mode
hoocode --tools read,SearchCodebase -p "Review the code"

Environment Variables

Design Principles

HooCode keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.

It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.