kapm

README

kapm

Observability and package compatibility tools for Kiro agent projects.

English · 日本語 · 한국어 · 简体中文

What kapm does

kapm helps you understand and maintain Kiro agent workspaces.

• Monitor Kiro sessions: read Kiro CLI v2 JSONL session logs (~/.kiro/sessions/cli/), Kiro IDE session logs (auto-detected), and Kiro CLI v1 SQLite session stores, supplemented by optional hook logs under .kapm/logs/ for tool-call timestamps, agent attribution, and shell exit status. Inspect sessions, tool calls, failures, durations, agents, prompts, responses, file changes, and skill reads in a terminal UI or WebUI.
• Manage Kiro agents: create and update .kiro/agents/*.json and .kiro/agent-prompts/*.md interactively.
• Bridge package formats: sync APM packages and Kiro Powers into project-local .kiro/ files.

Installation

Homebrew (macOS / Linux)

brew install --cask kapmcli/tap/kapm

Release archives

Download the archive for your platform from GitHub Releases, extract it, and place kapm or kapm.exe on your PATH.

Quick start

# Run Kiro, then inspect the recorded sessions.
# Terminal UI
kapm monitor
# Web UI
kapm serve

# Create or update a Kiro agent.
kapm agent generate

# Install kapm hook entries for selected agents.
kapm init-hook
# Install kapm hook files for Kiro IDE.
kapm init-ide-hook

Monitoring

kapm reads Kiro CLI v2 session data (~/.kiro/sessions/cli/{uuid}.jsonl logs with {uuid}.json metadata) as its primary data source. Kiro IDE session logs are also loaded automatically when available. Kiro CLI v1 SQLite session stores (conversations_v2) are also read when present. No hook installation is required for basic monitoring — sessions contain prompts, assistant responses, tool calls, tool results, and per-turn metadata (credits).

kapm init-hook optionally adds hook entries to .kiro/agents/*.json for supplementary CLI agent data. kapm init-ide-hook writes Kiro IDE hook files under .kiro/hooks/*.kiro.hook. CLI hooks write minimal records under .kapm/logs/cli/; IDE hooks write minimal records under .kapm/logs/ide/.

kapm init-hook             # select agents interactively
kapm init-hook --global    # select global agents under ~/.kiro/agents
kapm init-hook --remove    # remove kapm-managed hook entries
kapm init-ide-hook         # install workspace Kiro IDE hook files
kapm init-ide-hook --remove # remove kapm-managed IDE hook files

kapm monitor
kapm monitor --json
kapm monitor --json --session <session-id>
kapm monitor --json --session <session-id> --agent <agent-name>

kapm serve
kapm serve --port 9097 --open

Both monitor and serve support:

--since 24h
--global                   # show sessions from all projects (default: current directory only)
--logs-dir <path>
--target-dir <path>
--ide-sessions-dir <path>  # override auto-detected IDE sessions directory

WebUI routes

Route	Description
GET /	Overview dashboard
GET /sessions	Session list
GET /sessions/{id}	Merged session detail
GET /sessions/{id}/{agent}	Per-agent session detail
GET /agents	Agent list
GET /agents/{name}	Agent detail
GET /tools	Tool usage
GET /tools/{name}	Tool detail
GET /skills	Skill reads

Tool usage aggregates known tool aliases, and tool detail shows the observed alias distribution.

Agent configuration

kapm agent generate
kapm agent generate --force
kapm agent update <name>

agent generate creates .kiro/agents/<name>.json and .kiro/agent-prompts/<name>.md. agent update edits an existing agent and preserves unknown JSON fields.

APM compatibility

kapm sync
kapm sync --force

kapm install owner/repo
kapm install --update owner/repo
kapm install github/awesome-copilot/skills/review-and-refactor

kapm sync reads local .apm/, installed apm_modules/, and MCP dependencies from apm.yml, then writes Kiro-native files under .kiro/. Existing files are skipped unless --force is used.

kapm install delegates installation to apm install. If apm is not available, kapm falls back to uvx to run apm install. After installation, it runs the same sync step.

Additional kapm flags for install:

--sync-force            # overwrite .kiro files during the sync step
--target-dir <path>     # choose the project directory to sync into

--global is forwarded to APM and uses your home directory as the sync root. It cannot be combined with --target-dir.

Kiro Power compatibility

kapm power install ./local/power
kapm power install owner/repo
kapm power install owner/repo/path/to/power --ref main
kapm power install https://github.com/owner/repo
kapm power install https://github.com/owner/repo/tree/main/path/to/power

power install copies the raw Power package into .kiro/powers/<name>/. It does not synthesize a skill file, merge MCP settings, or activate hooks. Instead, it prints concrete follow-up snippets:

• file:// resource entries for POWER.md and steering/*.md
• mcpServers content when the Power includes mcp.json
• hook files to adapt when the Power includes hooks/
• a manual remove command

Use --force to overwrite an existing kapm-managed Power directory.

Compatibility mapping

Source	Kiro output
APM instructions	.kiro/steering/<name>.md
APM prompts	.kiro/prompts/<name>.md
APM commands	.kiro/prompts/<name>.md
APM skills	.kiro/skills/<name>/...
APM agents / chatmodes	.kiro/agents/<name>.json + .kiro/agent-prompts/<name>.md
APM MCP dependencies	.kiro/settings/mcp.json
Kiro Power package	.kiro/powers/<name>/...

Log format and retention

Hook logs use a minimal format: CLI records contain ts, session, event, agent, tool, and optionally shell_exit_status; IDE records contain ts, event, agent, and cwd. Prompts, tool input/output, and assistant responses are read from Kiro's session files, not from hook logs.

.kapm/ is gitignored, directories are created with 0700, and log files are created with 0600.

Development

just build
just test
just lint

If just is unavailable:

go build -o kapm ./cmd/kapm      # macOS / Linux
go build -o kapm.exe ./cmd/kapm  # Windows

Links

• APM docs · APM CLI · APM source
• Kiro prompts · Kiro skills · Kiro steering · Kiro custom agents
• design.md