@kikimoradev/kikimora

        every N minutes (only during working hours)
                          │
                          ▼
                  ┌───────────────┐   JSON report   ┌───────────────┐
                  │    MONITOR    │ ───────────────▶│   TaskStore   │
                  │    (haiku)    │     (tasks)     │  tasks.json   │
                  └───────────────┘                 └───────┬───────┘
                                                            │ wakes (Waker)
                                                            │
┌───────────────┐  session log  ┌───────────────┐  pending  │
│  SUMMARIZER   │ ◀──────────── │   EXECUTOR    │ ◀─────────┘
│   (sonnet)    │               │    (opus)     │
└───────┬───────┘               └───────┬───────┘
        │ findings                      │ memory_search / memory_get
        ▼                               ▼
┌───────────────────────────────────────────────┐
│            Memory (SQLite + FTS5)             │
│              MCP server (stdio)               │
└───────────────────────────────────────────────┘

The monitor and executor loops run in parallel and share only the task store:

• The monitor runs a session on an interval and returns tasks as JSON that matches an enforced schema.
• New tasks wake the executor, which takes them one at a time.
• Each executor session has full tool access and can search the summaries of earlier sessions.
• After an executor session, the summarizer reads its log and stores a summary in memory.

The models in the diagram are the defaults.

Use cases

The monitor prompt defines what counts as a task. Examples:

• CI repair: watch the pipeline on main, investigate failed builds, open a fix PR.
• Issue triage: pick up well-scoped bug reports and turn them into pull requests.
• Dependency updates: detect pending patch updates, bump them, run the tests.
• Backlog work: work through TODOs, flaky tests and lint findings.

A monitor prompt for the first two:

1. **CI on main**: run `gh run list --branch main --limit 5`. If the latest
   run failed, report a task to investigate and fix it (id: `ci-<run-id>`).
2. **Issues labeled `bug`**: for each issue describing a concrete,
   self-contained change, report a task with id `issue-<number>`.

Full examples and prompt-writing tips: docs/prompts.md.

Features

• Task loop: the monitor reports tasks and the executor completes them. /task adds a task by hand.
• Long-term memory: SQLite with FTS5, exposed to the executor over MCP (memory_search, memory_get).
• Interactive TUI: an Ink/React shell with live agent status, switchable views and slash commands.
• Working hours: a time window and days of the week (08:00-18:00, mon-fri) limit when the monitor runs.
• Retries: transient failures are retried up to maxTaskAttempts, other failures mark the task failed. Tasks left in_progress by a crash return to pending on the next start.
• Usage limits: when Claude Code reports its 5-hour or weekly limit, both agents wait with a countdown until the reset plus 60 s. The interrupted task returns to the queue and the attempt is not counted; after the reset the executor resumes the interrupted Claude Code session, told how long it waited, instead of starting over, and starts a fresh session only when that one cannot be resumed.
• Prompts in files: agent prompts are markdown files; the code contains no prompt text.

Quick start

Requirements:

• Node.js ^22.16.0 or >=24.0.0 (the engines field), an official build: long-term memory needs node:sqlite with FTS5.
• The Claude Code CLI (claude), installed and logged in.

npm install -g @kikimoradev/kikimora

cd your-project
kikimora          # first run asks for the two agent prompts, then opens the TUI

The first-run wizard asks for two prompts: what the monitor watches and how the executor works. Its multi-line editor accepts pasted markdown; Enter adds a line and Ctrl+D submits. All other settings start at their defaults and can be changed later with slash commands. In a terminal the agents start paused and run after /start.

From a clone: pnpm install && pnpm start.

The TUI

The screen has four parts:

• a one-line header: version, project directory, uptime, cost and cycle count;
• the current view, in framed panels whose borders carry the title, the model and the last outcome;
• a command input with history, tab completion of commands and their values (/model ex + Tab), and readline keys (Ctrl+A/E, Ctrl+W, Ctrl+U/K, Alt+←/→);
• a status bar with the view, a dot per agent and the keys for the current context; command results appear there for a few seconds.

PgUp/PgDn scrolls the focused agent panel or any list view (/tasks, /memory, /config, /help); Esc returns to the live tail. Below 100 columns the dashboard shows one agent at a time and Tab switches between them.

Configuration commands write to .kikimora/settings.json and take effect from the next agent session, without a restart.

Headless mode and servers

Without a TTY (systemd, Docker, CI, a pipe), kikimora skips the dashboard and starts the agents immediately. It prints line logs to stdout: human-readable by default, NDJSON with --log-format json. A second shell controls the running worker over a local control socket.

A second kikimora in the same project exits with an error while one is running.

• The control socket, its subcommands and the wire protocol: docs/control.md.
• Sessions that start only when a supervisor grants a slot, for many workers on one machine: external admission.
• The NDJSON event schema, a systemd runbook, authentication without a browser, the reference Dockerfile and docker-compose.yml, and the prebuilt images ghcr.io/kikimoradev/kikimora (plus a -browser variant with Chromium for Playwright MCP): docs/deployment.md.

Configuration

Per-project state lives in .kikimora/ inside the directory kikimora runs from, like Claude Code's .claude/. It holds settings.json, the project prompts and runtime data (tasks, memory, logs). The runtime data directories are listed in .kikimora/.gitignore, which setup writes.

settings.json is validated strictly and every section is optional. Change it with the slash commands above or by hand:

{
  "monitor": {
    "intervalMinutes": 15,
    "activeHours": "08:00-18:00",
    "activeDays": "mon-fri"
  },
  "executor": { "model": "opus", "effort": "high" }
}

All settings, the directory layout and what to commit: docs/configuration.md.

Security and costs

Warning: agents work directly in your project. Sessions run with --permission-mode bypassPermissions and full tool access in the directory kikimora runs from. Kikimora provides no sandbox. Run it only in projects where that is acceptable: reviewed prompts, no secrets within reach, version control to undo changes. Tasks reported by the monitor are input to an autonomous agent; the prompts set the boundaries.

Each monitor patrol and each task is a Claude Code session, and each session is billed. The bill scales with the interval and the models. Start with a long intervalMinutes and sonnet on the executor, then scale up once the prompts behave.

On the Anthropic API, fable costs twice the per-token rate of opus ($10 and $50 against $5 and $25 per million input and output tokens, Anthropic pricing as of June 2026). Use it on the executor for work that needs it. Working hours stop the monitor from patrolling outside the configured window.

Development

pnpm dev              # start with watch (tsx)
pnpm check            # typecheck + lint + format:check + test, before every commit
pnpm build            # tsup -> dist/

Tests run Claude sessions against a fake claude binary (test/fixtures/claude) and make no API calls. Coverage thresholds are enforced. See CONTRIBUTING.md.

License

MIT © Kikimora