MCP Tools Reference

kj_run

Run the full coder → sonar → reviewer pipeline with real-time progress notifications.

Parameter	Type	Required	Default	Description
`task`	string	Yes	—	Task description
`coder`	string	No	From config	AI agent for code generation
`coderModel`	string	No	`null`	Specific model for coder
`reviewer`	string	No	From config	AI agent for code review
`reviewerModel`	string	No	`null`	Specific model for reviewer
`reviewerFallback`	string	No	From config	Fallback reviewer if primary fails
`reviewerRetries`	number	No	`1`	Max review retries on parse error
`planner`	string	No	`null`	AI agent for planning
`plannerModel`	string	No	`null`	Specific model for planner
`refactorer`	string	No	`null`	AI agent for refactoring
`refactorerModel`	string	No	`null`	Specific model for refactorer
`mode`	string	No	`standard`	Review mode: `paranoid` \| `strict` \| `standard` \| `relaxed`
`methodology`	string	No	`tdd`	Development methodology: `tdd` \| `standard`
`maxIterations`	number	No	`5`	Max coder/reviewer loop iterations
`maxIterationMinutes`	number	No	`5`	Timeout per iteration (minutes)
`maxTotalMinutes`	number	No	From config	Total session timeout (minutes)
`baseBranch`	string	No	`main`	Git base branch for diffs
`baseRef`	string	No	`null`	Explicit base git ref for diff
`branchPrefix`	string	No	`feat/`	Git branch prefix
`enablePlanner`	boolean	No	`false`	Enable planning role
`enableReviewer`	boolean	No	`true`	Enable review role
`enableRefactorer`	boolean	No	`false`	Enable refactoring role
`enableResearcher`	boolean	No	`false`	Enable research role
`enableTester`	boolean	No	`false`	Enable test quality audit
`enableSecurity`	boolean	No	`false`	Enable OWASP security audit
`enableTriage`	boolean	No	`false`	Enable task complexity triage
`enableSerena`	boolean	No	`false`	Enable Serena semantic analysis
`autoCommit`	boolean	No	`false`	Auto-commit after approval
`autoPush`	boolean	No	`false`	Auto-push after commit
`autoPr`	boolean	No	`false`	Create PR after push
`autoRebase`	boolean	No	`true`	Rebase on base branch before push
`noSonar`	boolean	No	`false`	Skip SonarQube analysis
`pgTask`	string	No	`null`	Planning Game card ID (e.g., `PRJ-TSK-0042`)
`pgProject`	string	No	`null`	Planning Game project ID
`kjHome`	string	No	`~/.karajan`	Override KJ_HOME directory
`sonarToken`	string	No	From config	Override SonarQube token
`enableImpeccable`	boolean	No	`false`	Enable Impeccable design audit (automated UI/UX quality gate)
`enableHuReviewer`	boolean	No	`false`	Enable HU story certification (user story quality gate). Auto-activated by triage for medium/complex tasks since v1.38.0
`huFile`	string	No	`null`	Path to user story file for HU reviewer. Optional — when auto-activated by triage, hu-reviewer works without a file
`taskType`	string	No	`null`	Task type for policy resolution: `sw`, `infra`, `doc`, `add-tests`, `refactor`
`autoSimplify`	boolean	No	`true`	Auto-simplify pipeline for triage level 1-2 (coder-only, skip reviewer/tester). Set to `false` to always run the full pipeline
`timeoutMs`	number	No	`null`	Command timeout in milliseconds (legacy; prefer heartbeat/stall telemetry and session silence guardrails)

kj_code

Run coder-only mode — skip the review loop. Useful for quick changes.

Parameter	Type	Required	Default	Description
`task`	string	Yes	—	Task description
`coder`	string	No	From config	AI agent for coding
`coderModel`	string	No	`null`	Specific model for coder
`kjHome`	string	No	`~/.karajan`	Override KJ_HOME directory
`timeoutMs`	number	No	`null`	Command timeout in milliseconds (legacy; prefer heartbeat/stall telemetry and session silence guardrails)

kj_review

Run reviewer-only mode against the current diff. Useful after manual changes.

Parameter	Type	Required	Default	Description
`task`	string	Yes	—	Review task description
`reviewer`	string	No	From config	AI agent for review
`reviewerModel`	string	No	`null`	Specific model for reviewer
`baseRef`	string	No	`null`	Base ref for diff comparison
`kjHome`	string	No	`~/.karajan`	Override KJ_HOME directory
`timeoutMs`	number	No	`null`	Command timeout in milliseconds (legacy; prefer heartbeat/stall telemetry and session silence guardrails)

kj_plan

Generate an implementation plan without writing code, with heartbeat/stall telemetry and clearer diagnostics for long runs.

Parameter	Type	Required	Default	Description
`task`	string	Yes	—	Task description
`planner`	string	No	From config	AI agent for planning
`plannerModel`	string	No	`null`	Specific model for planner
`kjHome`	string	No	`~/.karajan`	Override KJ_HOME directory
`timeoutMs`	number	No	`null`	Command timeout in milliseconds (legacy; prefer heartbeat/stall telemetry and session silence guardrails)

kj_resume

Resume a paused session (e.g., after fail-fast or clarification question).

Parameter	Type	Required	Default	Description
`sessionId`	string	Yes	—	Session ID to resume (e.g., `s_2026-02-28T20-47-24-270Z`)
`answer`	string	No	`null`	Answer to the question that caused the pause
`kjHome`	string	No	`~/.karajan`	Override KJ_HOME directory

kj_report

Read and display session reports with budget tracking.

Parameter	Type	Required	Default	Description
`list`	boolean	No	`false`	List all session IDs instead of showing the latest
`sessionId`	string	No	Latest	Specific session ID to read
`format`	string	No	`text`	Output format: `text` \| `json`
`trace`	boolean	No	`false`	Show stage-by-stage breakdown with timing and costs
`currency`	string	No	`usd`	Cost display currency: `usd` \| `eur`
`kjHome`	string	No	`~/.karajan`	Override KJ_HOME directory

kj_scan

Run SonarQube scan on the current project.

Parameter	Type	Required	Default	Description
`kjHome`	string	No	`~/.karajan`	Override KJ_HOME directory
`sonarToken`	string	No	From config	Override SonarQube token
`timeoutMs`	number	No	`null`	Command timeout in milliseconds (legacy; prefer heartbeat/stall telemetry and session silence guardrails)

kj_init

Initialize karajan-code configuration, review rules, and SonarQube setup.

Parameter	Type	Required	Default	Description
`kjHome`	string	No	`~/.karajan`	Custom KJ_HOME directory
`timeoutMs`	number	No	`null`	Command timeout in milliseconds (legacy; prefer heartbeat/stall telemetry and session silence guardrails)

kj_doctor

Check system dependencies and agent CLIs (claude, codex, gemini, aider).

Parameter	Type	Required	Default	Description
`kjHome`	string	No	`~/.karajan`	Override KJ_HOME directory
`timeoutMs`	number	No	`null`	Command timeout in milliseconds (legacy; prefer heartbeat/stall telemetry and session silence guardrails)

kj_config

Show current configuration (pretty-print or JSON).

Parameter	Type	Required	Default	Description
`json`	boolean	No	`false`	Output as JSON instead of pretty-print
`kjHome`	string	No	`~/.karajan`	Override KJ_HOME directory

kj_roles

List pipeline roles or show a specific role template.

Parameter	Type	Required	Default	Description
`action`	string	No	`list`	Action: `list` \| `show`
`roleName`	string	No	`null`	Role to inspect (e.g., `coder`, `reviewer`, `reviewer-paranoid`)
`kjHome`	string	No	`~/.karajan`	Override KJ_HOME directory

kj_agents

List or change AI agent assignments per role. Supports session, project, and global scope.

Parameter	Type	Required	Default	Description
`action`	string	No	`list`	Action: `list` \| `set`
`role`	string	No	`null`	Role to change (e.g., `coder`, `reviewer`) — required for `set`
`provider`	string	No	`null`	Provider to assign (e.g., `claude`, `codex`) — required for `set`

kj_preflight

Human confirms agent configuration before kj_run/kj_code executes. Required before first run in each MCP session.

Parameter	Type	Required	Default	Description
`humanResponse`	string	Yes	—	Human’s response: `"ok"` to confirm, or natural language to adjust (e.g., `"use gemini as coder"`)
`coder`	string	No	`null`	Override coder agent
`reviewer`	string	No	`null`	Override reviewer agent
`tester`	string	No	`null`	Override tester agent
`security`	string	No	`null`	Override security agent
`solomon`	string	No	`null`	Override solomon agent
`enableTester`	boolean	No	`null`	Enable/disable tester role
`enableSecurity`	boolean	No	`null`	Enable/disable security role

kj_status

Show real-time status and log of the current or last Karajan run. Returns a parsed status summary (current stage, agent, iteration, errors) plus recent log lines.

Parameter	Type	Required	Default	Description
`lines`	number	No	`50`	Number of log lines to show

Response includes:

status.currentStage — which stage is currently running
status.currentAgent — which AI agent is active
status.iteration — current iteration number
status.isRunning — whether a run is in progress
status.errors — last 3 error lines

kj_audit

Read-only codebase health audit across 5 dimensions: security, code quality, performance, architecture, and testing. Generates a structured report with A-F scores and prioritized recommendations without modifying any files.

Parameter	Type	Required	Default	Description
`task`	string	No	`null`	Optional focus area or specific concern to audit
`projectDir`	string	No	cwd	Project directory to audit
`kjHome`	string	No	`~/.karajan`	Override KJ_HOME directory

kj_discover

Run discovery analysis on a task using multiple analytical frameworks (gaps, Mom Test, Wendel, JTBD).

Parameter	Type	Required	Default	Description
`task`	string	Yes	—	Task description to analyze
`mode`	string	No	`gaps`	Discovery mode: `gaps` \| `momtest` \| `wendel` \| `classify` \| `jtbd`
`projectDir`	string	No	cwd	Project directory

Example:

{
  "tool": "kj_discover",
  "params": {
    "task": "Add multi-tenancy support",
    "mode": "jtbd"
  }
}

kj_triage

Classify task complexity and determine which pipeline roles should be activated.

Parameter	Type	Required	Default	Description
`task`	string	Yes	—	Task description to classify
`projectDir`	string	No	cwd	Project directory

Example:

{
  "tool": "kj_triage",
  "params": {
    "task": "Fix typo in the README"
  }
}

kj_researcher

Investigate codebase context relevant to a task before planning or coding.

Parameter	Type	Required	Default	Description
`task`	string	Yes	—	Task description to research
`projectDir`	string	No	cwd	Project directory

Example:

{
  "tool": "kj_researcher",
  "params": {
    "task": "Refactor the authentication module"
  }
}

kj_architect

Design solution architecture for a task, producing a structured design document.

Parameter	Type	Required	Default	Description
`task`	string	Yes	—	Task description to architect
`projectDir`	string	No	cwd	Project directory

Example:

{
  "tool": "kj_architect",
  "params": {
    "task": "Migrate from REST to GraphQL"
  }
}

kj_board

Start, stop, or check the status of the HU Board dashboard.

Parameter	Type	Required	Default	Description
`action`	string	Yes	—	Action: `start` \| `stop` \| `status`
`projectDir`	string	No	cwd	Project directory

Example:

{
  "tool": "kj_board",
  "params": {
    "action": "start"
  }
}

kj_hu

Manage user stories (create, update, list, get) in the local HU Board.

Parameter	Type	Required	Default	Description
`action`	string	Yes	—	Action: `create` \| `update` \| `list` \| `get`
`title`	string	No	`null`	User story title (required for `create`)
`description`	string	No	`null`	User story description
`huId`	string	No	`null`	HU identifier (required for `update` and `get`)
`status`	string	No	`null`	HU status
`projectDir`	string	No	cwd	Project directory

Example:

{
  "tool": "kj_hu",
  "params": {
    "action": "create",
    "title": "As a user I want to reset my password",
    "description": "Password reset flow with email verification"
  }
}

kj_suggest

Send an observation to Solomon without interrupting the pipeline. Useful for providing context or hints that Solomon can consider in its next evaluation.

Parameter	Type	Required	Default	Description
`observation`	string	Yes	—	Observation or suggestion for Solomon
`sessionId`	string	No	Latest	Session ID to target
`projectDir`	string	No	cwd	Project directory

Example:

{
  "tool": "kj_suggest",
  "params": {
    "observation": "The reviewer is focusing on naming conventions — consider overriding"
  }
}

kj_skills

List, install, or remove domain-specific skills for pipeline roles. Skills extend coder, reviewer, and architect prompts with domain knowledge.

Parameter	Type	Required	Default	Description
`action`	string	No	`list`	Action: `list` \| `install` \| `remove`
`skill`	string	No	`null`	Skill identifier (required for `install` and `remove`)
`projectDir`	string	No	cwd	Project directory

Example:

{
  "tool": "kj_skills",
  "params": {
    "action": "install",
    "skill": "react-patterns"
  }
}

Common response format

All tools return a structured response:

Success:

{
  "ok": true,
  "sessionId": "s_...",
  ...
}

Error:

{
  "ok": false,
  "error": "Error message",
  "tool": "kj_run",
  "category": "sonar_unavailable",
  "suggestion": "Actionable fix suggestion"
}

Error categories: sonar_unavailable, auth_error, config_error, agent_missing, timeout, branch_error, agent_stall, git_error, unknown.