KCode Configuration

Config Files

File	Purpose
`~/.kcode/settings.json`	Global settings
`.kcode/settings.json`	Project-level settings
`.kcode/settings.local.json`	Local overrides (gitignored)
`~/.kcode/models.json`	Model registry
`KCODE.md`	Per-project instructions (like `.cursorrules`)
`.kcode/rules/`	Per-project rule files
`~/.kcode/permissions.json`	Global permission rules
`.kcode/permissions.json`	Project permission rules
`~/.kcode/agents/`	Custom agent definitions
`.kcode/agents/`	Project-scoped agents

Settings Priority

Highest priority first:

CLI flags (--model, --permission, etc.)
Managed policy locked settings (enterprise)
Environment variables (KCODE_MODEL, etc.)
.kcode/settings.local.json
.kcode/settings.json
~/.kcode/settings.json

Settings

// ~/.kcode/settings.json
{
  "theme": "dark",
  "permissionMode": "ask",
  "maxTokens": 8192,
  "mcpServers": {},
  "hooks": {}
}

Model Registry

# List configured models
kcode models list
 
# Add a model
kcode models add mnemo:mark5 --url http://localhost:10091
 
# Set default model
kcode models default mnemo:mark5
 
# Remove a model
kcode models rm old-model

Models are stored in ~/.kcode/models.json:

{
  "models": {
    "mnemo:mark5": {
      "url": "http://localhost:10091",
      "default": true
    }
  }
}

Environment Variables

Variable	Description
`KCODE_MODEL`	Override default model
`KCODE_API_BASE`	Override API base URL
`KCODE_API_KEY`	API key for remote providers

Project Rules

Create KCODE.md in your project root to give KCode project-specific instructions:

# Project Rules
 
- Use TypeScript strict mode
- All API responses must include error handling
- Tests go in __tests__/ directories
- Use pnpm, not npm

KCode loads this file at the start of every conversation in that project.

Permission Rules

Define fine-grained permission rules in ~/.kcode/permissions.json:

{
  "rules": [
    { "pattern": "Edit(src/**)", "action": "allow" },
    { "pattern": "Bash(rm *)", "action": "deny" },
    { "pattern": "Edit(/etc/**)", "action": "deny" }
  ]
}

Hooks

Configure lifecycle hooks in settings to run commands, inject prompts, or call webhooks on events:

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "echo 'Tool about to run'",
        "matcher": { "toolName": "Bash" }
      }
    ],
    "PostToolUse": [
      {
        "type": "http",
        "url": "https://hooks.example.com/audit",
        "method": "POST",
        "auth": "your-token"
      }
    ],
    "SessionStart": [
      {
        "type": "prompt",
        "prompt": "Remember: always write tests first"
      }
    ]
  }
}

Hook Events

28 hook events available:

Event	Description
`SessionStart` / `SessionEnd`	Session lifecycle
`PreToolUse` / `PostToolUse`	Before/after any tool execution
`PostToolUseFailure`	When a tool call errors
`PreEdit` / `PostEdit`	Before/after file edits
`PreBash` / `PostBash`	Before/after bash commands
`PreWrite` / `PostWrite`	Before/after file creation
`PreCompact` / `PostCompact`	Before/after context compaction
`UserPromptSubmit`	When user sends a message
`SubagentStart` / `SubagentStop`	Agent lifecycle
`ModelSwitch`	When model routing switches
`ContextOverflow`	When context nears capacity
`Notification`	Desktop notifications

Hook Types

Type	Description
`command`	Run a shell command (receives JSON on stdin)
`prompt`	Inject text into the conversation context
`http`	POST JSON to a webhook URL (supports `auth` for Bearer tokens)

Custom Agents

Define custom agents as .md files with YAML frontmatter in ~/.kcode/agents/:

---
name: reviewer
description: Code review specialist
model: mnemo:mark5-max
tools: [Read, Glob, Grep]
permissionMode: deny
maxTurns: 10
effort: high
memory: true
hooks:
  [{"event": "SubagentStart", "actions": [{"type": "command", "command": "echo reviewing"}]}]
---
 
You are a senior code reviewer. Focus on:
- Security vulnerabilities
- Performance issues
- Code quality and readability

Then use it: kcode --agent reviewer "review the auth module"

Built-in Tools Enterprise & Security