Kimix Knowledge
Kimix is a high-performance general-purpose AI agent (TUI + headless + ACP).
Local state lives under ~/.kimix/.
The user-guide next to the product is authoritative — it is extracted to
~/.kimix/docs/user-guide/ on startup from the same sources the TUI docs
picker uses. Never invent slash commands, config keys, tool names, or CLI
flags. Open the matching doc file and answer from it.
How to use this skill
- Pick the reference file(s) below that cover the question and read them.
- Answer from what they say; quote exact ids, flags, paths, and settings keys
verbatim.
- For building a plugin / hook / slash command / skill / MCP package
(Kimix "mod"), switch to
/mod-builder — do not improvise packaging here.
- Prefer a minimal working example over abstract theory when the doc has one.
Reference index
Path root: ~/.kimix/docs/user-guide/
| Topic |
File |
| Install / first run |
01-getting-started.md |
| Auth |
02-authentication.md |
| Keyboard shortcuts |
03-keyboard-shortcuts.md |
| Slash commands |
04-slash-commands.md |
Configuration (config.toml, env) |
05-configuration.md |
| Theming / appearance |
06-theming.md |
| MCP servers |
07-mcp-servers.md |
| Skills |
08-skills.md |
| Plugins |
09-plugins.md |
| Hooks |
10-hooks.md |
| Custom models |
11-custom-models.md |
| Project rules (AGENTS.md) |
12-project-rules.md |
| Memory |
13-memory.md |
| Headless / CI / scripting |
14-headless-mode.md |
| ACP / IDE / agent mode |
15-agent-mode.md |
| Subagents / personas |
16-subagents.md |
| Sessions |
17-sessions.md |
| Sandbox |
18-sandbox.md |
| Plan mode |
19-plan-mode.md |
| Background tasks / monitoring |
20-background-tasks.md |
| Terminal support / troubleshooting |
21-terminal-support.md |
| Permissions and safety |
22-permissions-and-safety.md |
| Agent dashboard |
23-dashboard.md |
| Usage / OpenTelemetry |
24-monitoring-usage.md |
| Building extensions (mods) |
25-building-extensions.md |
Also useful:
~/.kimix/config.toml, ~/.kimix/pager.toml, ~/.kimix/README.md- In-app:
/help docs picker, kimix inspect, kimix plugin …
Extension surface (Kimix "mods")
Kimix does not load TypeScript ModApi factories (Command Code style).
Practical layers, smallest → largest:
| Want |
Use |
Reusable procedure / /name prompt |
Skill (SKILL.md) or legacy commands/*.md |
| Lifecycle script (block tool, log, notify) |
Hook (hooks/*.json + command/HTTP) |
| Extra model-callable tools |
MCP server ([mcp_servers.*] or plugin .mcp.json) |
| Bundle skills + commands + agents + hooks + MCP + LSP |
Plugin (plugin.json + convention dirs) |
| Standing project instructions |
AGENTS.md |
| Cross-session facts |
Memory |
Command Code "mod" ≈ Kimix plugin (plus hooks/MCP), not a single TS file.
| Command Code |
Kimix |
cmd.addTool |
MCP tool (or skill driving built-ins) |
cmd.addCommand |
Skill slash / commands/*.md / plugin commands/ |
hooks.beforeToolCall |
PreToolUse hook |
hooks.afterToolCall |
PostToolUse / PostToolUseFailure |
transformInput / session hooks |
UserPromptSubmit / SessionStart / SessionEnd |
| package install |
kimix plugin install / drop into plugins dir |
Discovery (high level — details in the linked docs):
- Skills: CWD / repo
.kimix/skills → ~/.kimix/skills (+ compat roots)
- Hooks:
~/.kimix/hooks (always trusted) + project hooks (folder trust) + plugin hooks
- Plugins: session/cli dirs → project
.kimix/plugins (trust) → ~/.kimix/plugins
Built-in tools (model-facing)
Typical surface (hook matchers also accept Claude aliases):
- Files:
read_file, search_replace / write, list_dir, grep
- Shell:
run_terminal_command (alias Bash in matchers)
- Web:
web_search, web_fetch / page tools
- Agents:
spawn_subagent, background task controls
- Planning: todos, plan mode entry/exit
Performance posture
Kimix is tuned as a daily-driver agent (idle tick backoff, spinner frame-gating,
mouse motion without full repaint). When advising on extensions:
- Narrow hook matchers; short timeouts; fail-open on crash/timeout
- Prefer permission modes / sandbox over fragile always-on scripts for hard security
- Put expensive work off the PreToolUse hot path
Verify your answer
- Paths, flags, and config keys must appear in a user-guide file or
kimix --help /
kimix inspect output — if you cannot find it, say so rather than inventing.
- When the user should run something, prefer the exact command the doc shows
(e.g.
kimix plugin validate ./my-mod, kimix inspect).
- Building? Hand off to
/mod-builder and 25-building-extensions.md.
1---2name: kimix-knowledge3description: Answer questions about Kimix itself — features, config keys, slash commands, skills, plugins, hooks, MCP, permissions, sessions, headless/ACP, plan mode, memory, dashboard, and how to extend it. Prefer this skill over guessing product behavior. Also /kimix-knowledge.4---56# Kimix Knowledge78Kimix is a **high-performance general-purpose AI agent** (TUI + headless + ACP).9Local state lives under `~/.kimix/`.1011The **user-guide next to the product** is authoritative — it is extracted to12`~/.kimix/docs/user-guide/` on startup from the same sources the TUI docs13picker uses. **Never invent** slash commands, config keys, tool names, or CLI14flags. Open the matching doc file and answer from it.1516## How to use this skill17181. Pick the reference file(s) below that cover the question and **read them**.192. Answer from what they say; quote exact ids, flags, paths, and settings keys20 verbatim.213. For **building** a plugin / hook / slash command / skill / MCP package22 (Kimix "mod"), switch to `/mod-builder` — do not improvise packaging here.234. Prefer a minimal working example over abstract theory when the doc has one.2425## Reference index2627Path root: `~/.kimix/docs/user-guide/`2829| Topic | File |30|-------|------|31| Install / first run | `01-getting-started.md` |32| Auth | `02-authentication.md` |33| Keyboard shortcuts | `03-keyboard-shortcuts.md` |34| Slash commands | `04-slash-commands.md` |35| Configuration (`config.toml`, env) | `05-configuration.md` |36| Theming / appearance | `06-theming.md` |37| MCP servers | `07-mcp-servers.md` |38| Skills | `08-skills.md` |39| Plugins | `09-plugins.md` |40| Hooks | `10-hooks.md` |41| Custom models | `11-custom-models.md` |42| Project rules (AGENTS.md) | `12-project-rules.md` |43| Memory | `13-memory.md` |44| Headless / CI / scripting | `14-headless-mode.md` |45| ACP / IDE / agent mode | `15-agent-mode.md` |46| Subagents / personas | `16-subagents.md` |47| Sessions | `17-sessions.md` |48| Sandbox | `18-sandbox.md` |49| Plan mode | `19-plan-mode.md` |50| Background tasks / monitoring | `20-background-tasks.md` |51| Terminal support / troubleshooting | `21-terminal-support.md` |52| Permissions and safety | `22-permissions-and-safety.md` |53| Agent dashboard | `23-dashboard.md` |54| Usage / OpenTelemetry | `24-monitoring-usage.md` |55| **Building extensions (mods)** | `25-building-extensions.md` |5657Also useful:5859- `~/.kimix/config.toml`, `~/.kimix/pager.toml`, `~/.kimix/README.md`60- In-app: `/help` docs picker, `kimix inspect`, `kimix plugin …`6162## Extension surface (Kimix "mods")6364Kimix does **not** load TypeScript `ModApi` factories (Command Code style).65Practical layers, smallest → largest:6667| Want | Use |68|------|-----|69| Reusable procedure / `/name` prompt | **Skill** (`SKILL.md`) or legacy `commands/*.md` |70| Lifecycle script (block tool, log, notify) | **Hook** (`hooks/*.json` + command/HTTP) |71| Extra model-callable tools | **MCP server** (`[mcp_servers.*]` or plugin `.mcp.json`) |72| Bundle skills + commands + agents + hooks + MCP + LSP | **Plugin** (`plugin.json` + convention dirs) |73| Standing project instructions | **AGENTS.md** |74| Cross-session facts | **Memory** |7576Command Code "mod" ≈ Kimix **plugin** (plus hooks/MCP), not a single TS file.7778| Command Code | Kimix |79|--------------|--------|80| `cmd.addTool` | MCP tool (or skill driving built-ins) |81| `cmd.addCommand` | Skill slash / `commands/*.md` / plugin `commands/` |82| `hooks.beforeToolCall` | `PreToolUse` hook |83| `hooks.afterToolCall` | `PostToolUse` / `PostToolUseFailure` |84| `transformInput` / session hooks | `UserPromptSubmit` / `SessionStart` / `SessionEnd` |85| package install | `kimix plugin install` / drop into plugins dir |8687Discovery (high level — details in the linked docs):8889- **Skills:** CWD / repo `.kimix/skills` → `~/.kimix/skills` (+ compat roots)90- **Hooks:** `~/.kimix/hooks` (always trusted) + project hooks (folder trust) + plugin hooks91- **Plugins:** session/cli dirs → project `.kimix/plugins` (trust) → `~/.kimix/plugins`9293## Built-in tools (model-facing)9495Typical surface (hook matchers also accept Claude aliases):9697- Files: `read_file`, `search_replace` / `write`, `list_dir`, `grep`98- Shell: `run_terminal_command` (alias `Bash` in matchers)99- Web: `web_search`, `web_fetch` / page tools100- Agents: `spawn_subagent`, background task controls101- Planning: todos, plan mode entry/exit102103## Performance posture104105Kimix is tuned as a daily-driver agent (idle tick backoff, spinner frame-gating,106mouse motion without full repaint). When advising on extensions:107108- Narrow hook **matchers**; short **timeouts**; fail-open on crash/timeout109- Prefer permission modes / sandbox over fragile always-on scripts for hard security110- Put expensive work off the PreToolUse hot path111112## Verify your answer113114- Paths, flags, and config keys must appear in a user-guide file or `kimix --help` /115 `kimix inspect` output — if you cannot find it, say so rather than inventing.116- When the user should run something, prefer the exact command the doc shows117 (e.g. `kimix plugin validate ./my-mod`, `kimix inspect`).118- Building? Hand off to `/mod-builder` and `25-building-extensions.md`.
taxueseek