@kolisachint/hoocode-agent 0.5.26 → 0.5.28

package/docs/mcp.md

@@ -0,0 +1,97 @@
+# MCP servers
+
+hoocode speaks the Model Context Protocol, so tools from an MCP server appear
+alongside the built-in ones. Each server tool is registered as
+`mcp_<server>_<tool>` — a `create_pr` tool on a server named `github` becomes
+`mcp_github_create_pr`.
+
+## Configuring servers
+
+Config files are read in this order, **first wins by server name**:
+
+1. `~/.agents/mcp.json` — user, standard format
+2. `./.agents/mcp.json` — project, standard format
+3. `~/.config/claude/mcp.json` — Claude Desktop, standard format
+4. `~/.hoocode/mcp-servers/*.json` — user, one file per server
+5. `./.hoocode/mcp-servers/*.json` — project, one file per server
+
+Plugins can also declare servers in their manifest or a `.mcp.json` — see
+[Plugins](plugins.md).
+
+Standard format:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "my-mcp-server"],
+      "env": { "API_KEY": "..." }
+    }
+  }
+}
+```
+
+Per-server format (`.hoocode/mcp-servers/<name>.json`) uses a top-level `name`
+and `command` instead of the `mcpServers` wrapper.
+
+## Transports
+
+| Transport | Config | Notes |
+|-----------|--------|-------|
+| stdio | `"command"` (+ `args`, `env`) | Default when `command` is set |
+| Streamable HTTP | `{ "type": "http", "url": "..." }` | Add `headers` for auth |
+| SSE | `{ "type": "sse", "url": "..." }` | Legacy |
+
+One of `command` or `url` is required. Remote transports support OAuth; hoocode
+stores the tokens and runs the authorization callback for you when a server
+requires it.
+
+```json
+{
+  "mcpServers": {
+    "remote": {
+      "type": "http",
+      "url": "https://example.com/mcp",
+      "headers": { "Authorization": "Bearer ..." }
+    }
+  }
+}
+```
+
+## Deferred schemas
+
+A dozen MCP servers can contribute hundreds of tools, and their JSON schemas are
+the largest thing in a system prompt that is otherwise a few thousand tokens. So
+by default hoocode connects every server but **withholds the schemas**,
+registering one resolver tool instead:
+
+```
+ResolveMcpTools  names: ["mcp_github_create_pr"]
+ResolveMcpTools  query: "open a pull request"
+```
+
+Naming a tool resolves it; describing a capability finds it and resolves it, so
+the model does not have to know the name in advance. Resolved tools become
+callable in the same turn.
+
+Retrieval is hybrid — BM25 over tool names and descriptions, fused with a dense
+leg when the `embsearch` binary is present. The lexical leg always works and
+never needs a download, so an exact name match is guaranteed; the dense leg only
+adds. When only the lexical leg answered, the result says so.
+
+Turn deferral off with the `deferMcpSchemas` setting (default `true`) to load
+every schema eagerly. Subagent children never defer — they are spawned with a
+narrow tool allowlist already.
+
+## Checking status
+
+Connection happens at session start. A server that fails to connect reports an
+error notification and the session continues without it, rather than failing to
+start.
+
+## Related
+
+- [Settings](settings.md) — `deferMcpSchemas` and tool policy
+- [Plugins](plugins.md) — plugins that ship MCP servers, and the trust rule that governs them
+- [Project-local resources](project-local-resources.md) — the full `.agents/` discovery table

package/docs/models.md

@@ -1,6 +1,6 @@
 # Custom Models
 
-Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.hoocode/agent/models.json`.
+Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.hoocode/models.json`.
 
 ## Table of Contents
 

package/docs/modes.md

@@ -0,0 +1,87 @@
+# 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. Modes
+change *instructions*, not permissions: the tool policy in
+[Settings](settings.md) is what actually blocks a write. A read-only mode tells
+the model not to edit; it does not stop a tool call on its own.
+
+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, grep, trace, and explain, citing paths and line numbers; decline edits and suggest `/mode build` |
+| `plan` | Designing a change before making it | Explore, ask clarifying questions, then write a plan with Goal / Files to modify / New files / Tests / Verification |
+| `build` | Implementing | One tool per turn, read before editing, show diffs, confirm destructive operations, 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 |
+
+## 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
+
+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`.
+
+## Related
+
+- [Settings](settings.md) — tool policy, which is what actually restricts writes
+- [Prompt templates](prompt-templates.md) — reusable prompts, as opposed to a persistent stance
+- [Subagent delegation](routing.md) — handing focused work to a separate agent

package/docs/packages.md

@@ -36,7 +36,7 @@ hoocode update npm:@foo/bar      # update one package
 hoocode update --extension npm:@foo/bar
 ```
 
-By default, `install` and `remove` write to global settings (`~/.hoocode/agent/settings.json`). Use `-l` to write to project settings (`.hoocode/settings.json`) instead. Project settings can be shared with your team, and hoocode installs any missing packages automatically on startup.
+By default, `install` and `remove` write to global settings (`~/.hoocode/settings.json`). Use `-l` to write to project settings (`.hoocode/settings.json`) instead. Project settings can be shared with your team, and hoocode installs any missing packages automatically on startup.
 
 To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:
 
@@ -84,7 +84,7 @@ ssh://git@github.com/user/repo@v1
 - SSH URLs use your configured SSH keys automatically (respects `~/.ssh/config`).
 - For non-interactive runs (for example CI), you can set `GIT_TERMINAL_PROMPT=0` to disable credential prompts and set `GIT_SSH_COMMAND` (for example `ssh -o BatchMode=yes -o ConnectTimeout=5`) to fail fast.
 - Refs pin the package and skip package updates (`hoocode update`, `hoocode update --extensions`).
-- Cloned to `~/.hoocode/agent/git/<host>/<path>` (global) or `.hoocode/git/<host>/<path>` (project).
+- Cloned to `~/.hoocode/git/<host>/<path>` (global) or `.hoocode/git/<host>/<path>` (project).
 - Runs `npm install` after clone or pull if `package.json` exists.
 
 **SSH examples:**
@@ -163,7 +163,7 @@ If no `pi` manifest is present, hoocode auto-discovers resources from these dire
 
 Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When hoocode installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.
 
-Pi bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@kolisachint/hoocode-ai`, `@kolisachint/hoocode-agent-core`, `@kolisachint/hoocode-agent`, `@kolisachint/hoocode-tui`, `typebox`.
+HooCode bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@kolisachint/hoocode-ai`, `@kolisachint/hoocode-agent-core`, `@kolisachint/hoocode-agent`, `@kolisachint/hoocode-tui`, `typebox`.
 
 Other hoocode packages must be bundled in your tarball. Add them to `dependencies` and `bundledDependencies`, then reference their resources through `node_modules/` paths. HooCode loads packages with separate module roots, so separate installs do not collide or share modules.
 
@@ -212,7 +212,7 @@ Filter what a package loads using the object form in settings:
 
 ## Enable and Disable Resources
 
-Use `hoocode config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (`~/.hoocode/agent`) and project (`.hoocode/`) scopes.
+Use `hoocode config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (`~/.hoocode`) and project (`.hoocode/`) scopes.
 
 ## Scope and Deduplication
 

package/docs/plugins.md

@@ -0,0 +1,124 @@
+# Plugins
+
+A plugin is a directory that bundles capabilities — skills, slash commands,
+subagents, hooks, MCP servers, themes, and canvas extensions — behind one
+installable name. Plugins come from marketplaces, which are git repositories or
+local directories that index them.
+
+Plugins overlap with [hoocode packages](packages.md); the difference is where
+they come from and who installs them. A package is an npm or git dependency you
+list in settings. A plugin is installed by name from a marketplace, can be
+installed by the model mid-task, and is portable across agent tools —
+hoocode reads the Claude Code and GitHub Copilot plugin formats as well as its
+own.
+
+## Using plugins
+
+```
+/plugin marketplace add <git-url|path>   # register a marketplace (a human act)
+/plugin marketplace list                 # what is registered
+/plugin marketplace refresh              # re-fetch marketplace indices
+/plugin list                             # what is installed
+/plugin install <name> [--scope user|project]
+/plugin remove <name>
+```
+
+`--scope user` (the default) installs under your agent dir, for every project.
+`--scope project` installs into the current repository, where it travels with
+the clone.
+
+## Trust
+
+Two different decisions, deliberately kept apart:
+
+**Adding a marketplace is a human act.** It says you accept code from that
+source. Nothing installs a marketplace for you.
+
+**Installing from a marketplace you already added is the model's discretion** —
+the package-manager model. hoocode announces what it installed and the install
+is reversible with `/plugin remove`.
+
+Separately, a plugin committed to a repository is code that runs for whoever
+clones it next. Its skills and commands are only text the model reads, no worse
+than reading the repository itself, but **its hooks and MCP servers are
+processes that start when the session loads**. So hoocode keeps a per-machine
+record of which working directories you have agreed to run repository-supplied
+plugin code from:
+
+```
+/plugin trust [list]   # inspect, or grant trust for this workspace
+/plugin untrust        # revoke it
+```
+
+The record lives in your agent dir, keyed by absolute path — outside the
+repository, so repository content cannot forge it. Until a workspace is trusted,
+a repo-supplied plugin loads with its hooks and MCP servers held back; hoocode
+reports this as a warning at startup rather than failing the session.
+
+Granting trust is always a human act. The autonomous install path never grants
+it. As with VS Code's trusted folders, trust is a statement about a place you
+work, not about a specific commit — code pulled into a trusted directory later
+is trusted too.
+
+## What a plugin can contain
+
+A directory is recognized as a plugin if it has a `plugin.json` manifest or any
+of these:
+
+| Path | Provides |
+|------|----------|
+| `skills/` | Agent Skills ([Skills](skills.md)) |
+| `commands/` | Slash commands |
+| `agents/` | Subagent definitions ([Subagent delegation](routing.md)) |
+| `hooks/`, `hooks/hooks.json` | Lifecycle hooks |
+| `.mcp.json` | MCP servers ([MCP](mcp.md)) |
+| `SKILL.md` | A single-skill plugin |
+
+Read from the manifest but not sufficient on their own to mark a directory as a
+plugin: `themes/` and `extensions/` (canvas extensions — see [Canvas](canvas.md)).
+
+## Formats
+
+hoocode reads three on-disk layouts, so a plugin written for another agent tool
+generally works unchanged:
+
+| Format | Marker | Notes |
+|--------|--------|-------|
+| hoocode (native) | `plugin.json` | The only format with `providers` |
+| Claude Code | `.claude-plugin/` | Same component layout, no `providers` |
+| GitHub Copilot | `.github/plugin/` | Also read from the plugin root, `.plugin/`, and `.claude-plugin/`; written to `.github/plugin/` |
+
+## Authoring
+
+Scaffold the pieces:
+
+```
+/new-skill <name>
+/new-agent <name>
+/new-command <name>
+/new-canvas <name>
+```
+
+Then package for distribution:
+
+```
+/plugin publish <name> [--to <dir>]
+```
+
+## Model-facing tools
+
+When plugin tooling is enabled (`--enable-plugintools`, or the
+`enablePluginTools` setting), the model gets its own lifecycle tools rather than
+going through the slash command: `SearchPlugins`, `ListPlugins`,
+`SuggestPluginInstall`, `InstallPlugin`, `UninstallPlugin`, `UpdatePlugin`,
+`ProposePlugin`, `RemovePluginCapability`, and `PackagePlugin`.
+
+`SearchPlugins` matches on capability, not just name — a plugin described as
+"compose and send mail" is findable by a search for "email" — so the model can
+close a capability gap mid-task instead of hand-rolling a solution.
+
+## Related
+
+- [HooCode packages](packages.md) — npm/git-distributed bundles you list in settings
+- [Skills](skills.md), [Extensions](extensions.md), [MCP](mcp.md), [Canvas](canvas.md)
+- [Project-local resources](project-local-resources.md) — the `.agents/` conventions plugins build on

package/docs/prompt-templates.md

@@ -8,7 +8,7 @@ Prompt templates are Markdown snippets that expand into full prompts. Type `/nam
 
 HooCode loads prompt templates from:
 
-- Global: `~/.hoocode/agent/prompts/*.md`
+- Global: `~/.hoocode/prompts/*.md`
 - Project: `.hoocode/prompts/*.md`
 - Packages: `prompts/` directories or `pi.prompts` entries in `package.json`
 - Settings: `prompts` array with files or directories

package/docs/providers.md

@@ -20,7 +20,7 @@ Use `/login` in interactive mode, then select a provider:
 - Claude Pro/Max
 - GitHub Copilot
 
-Use `/logout` to clear credentials. Tokens are stored in `~/.hoocode/agent/auth.json` and auto-refresh when expired.
+Use `/logout` to clear credentials. Tokens are stored in `~/.hoocode/auth.json` and auto-refresh when expired.
 
 ### OpenAI Codex
 
@@ -49,7 +49,7 @@ hoocode
 
 ### Auth File
 
-Store credentials in `~/.hoocode/agent/auth.json`:
+Store credentials in `~/.hoocode/auth.json`:
 
 ```json
 {

package/docs/quickstart.md

@@ -40,7 +40,7 @@ export ANTHROPIC_API_KEY=sk-ant-...
 hoocode
 ```
 
-You can also run `/login` and select an API-key provider to store the key in `~/.hoocode/agent/auth.json`.
+You can also run `/login` and select an API-key provider to store the key in `~/.hoocode/auth.json`.
 
 See [Providers](providers.md) for all supported providers, environment variables, and cloud-provider setup.
 
@@ -75,7 +75,7 @@ HooCode loads context files at startup. Add an `AGENTS.md` file to tell it how t
 
 HooCode loads:
 
-- `~/.hoocode/agent/AGENTS.md` for global instructions
+- `~/.hoocode/AGENTS.md` for global instructions
 - `AGENTS.md` or `CLAUDE.md` from parent directories and the current directory
 
 Restart hoocode, or run `/reload`, after changing context files.

package/docs/rpc.md

@@ -714,9 +714,9 @@ Response:
   "success": true,
   "data": {
     "commands": [
-      {"name": "session-name", "description": "Set or clear session name", "source": "extension", "path": "/home/user/.hoocode/agent/extensions/session.ts"},
-      {"name": "fix-tests", "description": "Fix failing tests", "source": "prompt", "location": "project", "path": "/home/user/myproject/.hoocode/agent/prompts/fix-tests.md"},
-      {"name": "skill:brave-search", "description": "Web search via Brave API", "source": "skill", "location": "user", "path": "/home/user/.hoocode/agent/skills/brave-search/SKILL.md"}
+      {"name": "session-name", "description": "Set or clear session name", "source": "extension", "path": "/home/user/.hoocode/extensions/session.ts"},
+      {"name": "fix-tests", "description": "Fix failing tests", "source": "prompt", "location": "project", "path": "/home/user/myproject/.hoocode/prompts/fix-tests.md"},
+      {"name": "skill:brave-search", "description": "Web search via Brave API", "source": "skill", "location": "user", "path": "/home/user/.hoocode/skills/brave-search/SKILL.md"}
     ]
   }
 }
@@ -730,8 +730,8 @@ Each command has:
   - `"prompt"`: Loaded from a prompt template `.md` file
   - `"skill"`: Loaded from a skill directory (name is prefixed with `skill:`)
 - `location`: Where it was loaded from (optional, not present for extensions):
-  - `"user"`: User-level (`~/.hoocode/agent/`)
-  - `"project"`: Project-level (`./.hoocode/agent/`)
+  - `"user"`: User-level (`~/.hoocode/`)
+  - `"project"`: Project-level (`./.hoocode/`)
   - `"path"`: Explicit path via CLI or settings
 - `path`: Absolute file path to the command source (optional)
 

package/docs/sdk.md

@@ -338,7 +338,7 @@ const { session } = await createAgentSession({
   cwd: process.cwd(), // default
   
   // Global config directory
-  agentDir: "~/.hoocode/agent", // default (expands ~)
+  agentDir: "~/.hoocode", // default (expands ~)
 });
 ```
 
@@ -354,7 +354,7 @@ const { session } = await createAgentSession({
 `agentDir` is used by `DefaultResourceLoader` for:
 - Global extensions (`extensions/`)
 - Global skills:
-  - `skills/` under `agentDir` (for example `~/.hoocode/agent/skills/`)
+  - `skills/` under `agentDir` (for example `~/.hoocode/skills/`)
   - `~/.agents/skills/`
 - Global prompts (`prompts/`)
 - Global context file (`AGENTS.md`)
@@ -418,7 +418,7 @@ API key resolution priority (handled by AuthStorage):
 ```typescript
 import { AuthStorage, ModelRegistry } from "@kolisachint/hoocode-agent";
 
-// Default: uses ~/.hoocode/agent/auth.json and ~/.hoocode/agent/models.json
+// Default: uses ~/.hoocode/auth.json and ~/.hoocode/models.json
 const authStorage = AuthStorage.create();
 const modelRegistry = ModelRegistry.create(authStorage);
 
@@ -560,7 +560,7 @@ Custom tools passed via `customTools` are combined with extension-registered too
 
 ### Extensions
 
-Extensions are loaded by the `ResourceLoader`. `DefaultResourceLoader` discovers extensions from `~/.hoocode/agent/extensions/`, `.hoocode/extensions/`, and settings.json extension sources.
+Extensions are loaded by the `ResourceLoader`. `DefaultResourceLoader` discovers extensions from `~/.hoocode/extensions/`, `.hoocode/extensions/`, and settings.json extension sources.
 
 ```typescript
 import { createAgentSession, DefaultResourceLoader } from "@kolisachint/hoocode-agent";
@@ -818,7 +818,7 @@ const { session } = await createAgentSession({
 **Project-specific settings:**
 
 Settings load from two locations and merge:
-1. Global: `~/.hoocode/agent/settings.json`
+1. Global: `~/.hoocode/settings.json`
 2. Project: `<cwd>/.hoocode/settings.json`
 
 Project overrides global. Nested objects merge keys. Setters modify global settings by default.

package/docs/session-format.md

@@ -5,14 +5,14 @@ Sessions are stored as JSONL (JSON Lines) files. Each line is a JSON object with
 ## File Location
 
 ```
-~/.hoocode/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
+~/.hoocode/sessions/--<path>--/<timestamp>_<uuid>.jsonl
 ```
 
 Where `<path>` is the working directory with `/` replaced by `-`.
 
 ## Deleting Sessions
 
-Sessions can be removed by deleting their `.jsonl` files under `~/.hoocode/agent/sessions/`.
+Sessions can be removed by deleting their `.jsonl` files under `~/.hoocode/sessions/`.
 
 HooCode also supports deleting sessions interactively from `/resume` (select a session and press `Ctrl+D`, then confirm). When available, hoocode uses the `trash` CLI to avoid permanent deletion.
 
@@ -28,7 +28,7 @@ Existing sessions are automatically migrated to the current version (v3) when lo
 
 ## Source Files
 
-Source on GitHub ([pi-mono](https://github.com/kolisachint/hoocode)):
+Source on GitHub ([hoocode](https://github.com/kolisachint/hoocode)):
 - [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/kolisachint/hoocode/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
 - [`packages/coding-agent/src/core/messages.ts`](https://github.com/kolisachint/hoocode/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
 - [`packages/ai/src/types.ts`](https://github.com/kolisachint/hoocode/blob/main/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)

package/docs/sessions.md

@@ -4,7 +4,7 @@ HooCode saves conversations as sessions so you can continue work, branch from ea
 
 ## Session Storage
 
-Sessions auto-save to `~/.hoocode/agent/sessions/`, organized by working directory. Each session is a JSONL file with a tree structure.
+Sessions auto-save to `~/.hoocode/sessions/`, organized by working directory. Each session is a JSONL file with a tree structure.
 
 ```bash
 hoocode -c                  # Continue most recent session

package/docs/settings.md

@@ -4,7 +4,7 @@ HooCode uses JSON settings files with project settings overriding global setting
 
 | Location | Scope |
 |----------|-------|
-| `~/.hoocode/agent/settings.json` | Global (all projects) |
+| `~/.hoocode/settings.json` | Global (all projects) |
 | `.hoocode/settings.json` | Project (current directory) |
 
 Edit directly or use `/settings` for common options.
@@ -244,7 +244,7 @@ window.
 
 These settings define where to load extensions, skills, prompts, and themes from.
 
-Paths in `~/.hoocode/agent/settings.json` resolve relative to `~/.hoocode/agent`. Paths in `.hoocode/settings.json` resolve relative to `.hoocode`. Absolute paths and `~` are supported.
+Paths in `~/.hoocode/settings.json` resolve relative to `~/.hoocode`. Paths in `.hoocode/settings.json` resolve relative to `.hoocode`. Absolute paths and `~` are supported.
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
@@ -313,7 +313,7 @@ See [packages.md](packages.md) for package management details.
 Project settings (`.hoocode/settings.json`) override global settings. Nested objects are merged:
 
 ```json
-// ~/.hoocode/agent/settings.json (global)
+// ~/.hoocode/settings.json (global)
 {
   "theme": "dark",
   "compaction": { "enabled": true, "reserveTokens": 16384 }

package/docs/shell-aliases.md

@@ -2,7 +2,7 @@
 
 HooCode runs bash in non-interactive mode (`bash -c`), which doesn't expand aliases by default.
 
-To enable your shell aliases, add to `~/.hoocode/agent/settings.json`:
+To enable your shell aliases, add to `~/.hoocode/settings.json`:
 
 ```json
 {

package/docs/skills.md

@@ -24,7 +24,7 @@ HooCode implements the [Agent Skills standard](https://agentskills.io/specificat
 HooCode loads skills from:
 
 - Global:
-  - `~/.hoocode/agent/skills/`
+  - `~/.hoocode/skills/`
   - `~/.agents/skills/`
 - Project:
   - `.hoocode/skills/`
@@ -34,7 +34,7 @@ HooCode loads skills from:
 - CLI: `--skill <path>` (repeatable, additive even with `--no-skills`)
 
 Discovery rules:
-- In `~/.hoocode/agent/skills/` and `.hoocode/skills/`, direct root `.md` files are discovered as individual skills
+- In `~/.hoocode/skills/` and `.hoocode/skills/`, direct root `.md` files are discovered as individual skills
 - In all skill locations, directories containing `SKILL.md` are discovered recursively
 - In `~/.agents/skills/` and project `.agents/skills/`, root `.md` files are ignored
 

package/docs/terminal-setup.md

@@ -24,7 +24,7 @@ That mapping sends a raw linefeed byte. Inside hoocode, that is indistinguishabl
 
 If Claude Code 2.x or newer is the only reason you added that mapping, you can remove it, unless you want to use Claude Code in tmux, where it still requires that Ghostty mapping.
 
-If you want `Shift+Enter` to keep working in tmux via that remap, add `ctrl+j` to your hoocode `newLine` keybinding in `~/.hoocode/agent/keybindings.json`:
+If you want `Shift+Enter` to keep working in tmux via that remap, add `ctrl+j` to your hoocode `newLine` keybinding in `~/.hoocode/keybindings.json`:
 
 ```json
 {

package/docs/termux.md

@@ -20,7 +20,7 @@ pkg install nodejs termux-api git
 npm install -g @kolisachint/hoocode-agent
 
 # Create config directory
-mkdir -p ~/.hoocode/agent
+mkdir -p ~/.hoocode
 
 # Run hoocode
 hoocode
@@ -34,7 +34,7 @@ Image clipboard is not supported on Termux (the `ctrl+v` image paste feature wil
 
 ## Example AGENTS.md for Termux
 
-Create `~/.hoocode/agent/AGENTS.md` to help the agent understand the Termux environment:
+Create `~/.hoocode/AGENTS.md` to help the agent understand the Termux environment:
 
 ```markdown
 # Agent Environment: Termux on Android

package/docs/themes.md

@@ -20,7 +20,7 @@ Themes are JSON files that define colors for the TUI.
 HooCode loads themes from:
 
 - Built-in: every `*.json` in the shipped theme directory (see [Built-in Themes](#built-in-themes))
-- Global: `~/.hoocode/agent/themes/*.json`
+- Global: `~/.hoocode/themes/*.json`
 - Project: `.hoocode/themes/*.json`
 - Packages: `themes/` directories or `pi.themes` entries in `package.json`
 - Settings: `themes` array with files or directories
@@ -113,8 +113,8 @@ On first run, hoocode detects your terminal background and defaults to `dark` or
 1. Create a theme file:
 
 ```bash
-mkdir -p ~/.hoocode/agent/themes
-vim ~/.hoocode/agent/themes/my-theme.json
+mkdir -p ~/.hoocode/themes
+vim ~/.hoocode/themes/my-theme.json
 ```
 
 2. Define the theme with all required colors (see [Color Tokens](#color-tokens)):