Shikiru (しきる)

Shikiru coordinates coding agents through a defined development workflow: turn a request into reviewed changes, integrate them, and ask you when a decision needs human judgment. It runs locally with Git worktrees, a persistent engine and a terminal dashboard in tmux. Claude Code and Codex CLI are built in; different agents and models can work on the same task in different roles.

To have routine escalations handled for you, and the rest forwarded to your phone, see the companion service shikiri-yaku.

I designed and implemented Shikiru from my own experience developing software with AI agents. No existing tool covered all the workflows I needed, so I built one that does.

How it works

A request receives a task ID such as T-1, its own branch and a Git worktree. The Leader normally triages it into one of two routes:

• Implement: the Implementer makes changes; the Leader accepts them, requests another iteration, raises an Operator decision, or replaces the task with more suitable tasks.
• Plan: the Leader commits a plan and can create dependent follow-up tasks when the request asks for execution. A request only to produce a plan can finish with the plan itself.

Accepted changes are rebased onto the configured base and integrated locally or through a GitHub pull request. Conflicts go through bounded Implementer repair and Leader review. Requests needing your input, exhausted recovery limits and unsafe integration conditions become escalations (E-1, etc.) with context and applicable answers. Other eligible tasks can continue.

You can submit work with explicit mode, complexity, priority, dependencies or role/model choices. Independent tasks run in parallel up to the configured slot limit; dependencies, pauses, resource pressure and provider quota can delay dispatch. Each task retains reports, Git facts, agent sessions and a timeline so you can understand both its result and how it got there.

Requirements and installation

• Python 3.14+ and uv; Git 2.45+ and tmux 3.5+.
• A single Git repository per project, initialized at its root with at least one commit. Submodules and multi-repository projects are unsupported.
• Claude Code or Codex CLI installed and configured for your account.
• gh and an accessible GitHub remote if you choose pull-request integration.

Installation

uv tool install shikiru-cli
shikiru --help

The distribution is shikiru-cli; the command and the Python package are shikiru.

Before the first PyPI release, install the wheel from the latest release on the Releases page. Never install a long-running copy with --editable: an editable install follows the working tree. For development, see From a checkout.

Updating

uv tool upgrade shikiru-cli

An engine keeps the code it was started with, so run shikiru restart in each project with a running engine afterwards. restart refuses while a task runs unless --force is given.

Installations from before the rename (distribution shikiru) must switch once: the tool changed its distribution name, and both provide the executable shikiru, so they cannot be installed together. Run uv tool uninstall shikiru, then uv tool install shikiru-cli, then shikiru restart in each project with a running engine.

Going back

uv tool install shikiru-cli==<version>

Replace <version> with the release to return to, then run shikiru restart in each project with a running engine.

From a checkout

For development from a source checkout, follow CONTRIBUTING.md.

macOS is the platform exercised locally. CI is configured for Ubuntu 24.04 and macOS 15; see workflow runs for platform-specific results.

Initialize and run

Start at the root of a committed project repository:

cd /path/to/project
shikiru init
shikiru doctor
shikiru start
shikiru submit "Fix a small, specific issue and verify it"
shikiru attach

The eight-step wizard checks the repository, builds role/model/effort ladders, lets you choose tracker files and ignored cache paths, sets the orchestration limits, reviews each agent's options and chooses the integration mode, then writes .shikiru/config.toml and runs Doctor. The Orchestration step sets the maximum parallel tasks, the maximum passes per task, the maximum quota wait in seconds, the stall and tool timeouts in seconds (the silence allowed before a turn is stopped as stalled, without and with a running tool), the push interval in seconds (default 14400, four hours; 0 pushes after every local integration), the host CPU percentage below which new tasks may start, and the free RAM in GB that must be available before a new task starts. Each field starts at the project default, and Finish rejects an out-of-range value by focusing that field before anything is written. The Agents step lists the options each installed agent plugin offers (for the built-in Claude Code and Codex plugins: the compaction threshold in percent, the billing declaration, left unset unless you choose one, and extra CLI arguments split like a shell command line). They are written explicitly under [agents.<name>.options] so you can edit them later; an invalid value focuses its field and nothing is written. An agent plugin without the settings capability is named on that step and keeps its own defaults. Available model and effort choices come from agent plugins; where no authoritative catalog exists, Doctor cannot promise model availability. Tracker and cache fields start empty: add only what you want Shikiru to use. Cancel explicitly with the Cancel button; Ctrl+F briefly reveals the background artwork.

shikiru init --yes skips the wizard and writes editable defaults with model placeholders. Replace them with models supported by your agent, review the config, and run Doctor before starting. Ordinary doctor checks environment, config, plugins and state without running task turns; doctor --probe additionally runs live agent-contract checks and can consume paid provider usage.

CLI

Project commands find the nearest .shikiru/ above the current directory; use the global --project PATH to select a project explicitly. --help on each command describes its arguments and defaults; the root help also offers shell-completion setup and --version.

For example, skip triage for a known implementation, choose a complexity ladder and wait for another task:

shikiru submit --mode implement --complexity high --priority 10 --after T-1 "Implement the accepted design"
shikiru status T-2 --watch
shikiru --json status
shikiru --project /path/to/project --set orchestration.max_parallel=1 start

--after is repeatable. --leader and --implementer pin a role using agent:model[:effort]; obtain supported IDs from your installed agent and wizard. Global --json provides machine-readable command results. Queue acknowledgement and a task ID mean the request was recorded, not that the work finished; inspect status or the dashboard for the outcome.

Session discovery preserves healthy results alongside diagnostics for stale or unreadable project state, with applicable repair commands. ls exits nonzero when discovery is incomplete. Deleting .shikiru/ loses its state; initialization creates new state, not a recovery of deleted tasks. Shikiru permits one attached client per project session and refuses a second attachment rather than changing the existing terminal. Detach that client before moving to another terminal.

Dashboard and Operator control

Home shows the engine, repository cleanliness, task queue, active work, decisions and usage. Up/Down selects tasks; f filters status, / searches by ID or title, and m loads older tasks when offered. Task details bring together the current briefing, results, dependencies and related tasks, reports/Git evidence, event and agent activity, usage, sessions and workspace access. Timelines support paging, following the latest entries and agent-activity filters by role/turn. Use ? for context-specific navigation help.

Open Actions with Ctrl+P or F12 in the dashboard, or your tmux prefix followed by Space in any Shikiru pane. Actions apply to the selected task and, where appropriate, a chosen role. Availability depends on task/session state; More… exposes additional controls.

The task's tmux window provides role panes and a shell. Task details can open that workspace; resuming the agent interactively through Take over is different from just viewing its output. The default tmux prefix is Ctrl+B; prefix then d detaches without stopping the engine. shikiru attach reconnects later.

Built-in widgets include usage/quota, host and process CPU/RAM, disk space and project/run sizes, Docker container health/resource use, and engine faults. Docker is optional; unavailable samples are reported. The configured widget list controls what is enabled; extended views are available through Actions. Pane layouts, titles, refresh rates, warning thresholds and animation are configurable.

Agents, ladders and recovery

A rung is one agent/model/effort choice. A ladder is an ordered list of rungs: it lets Shikiru progress to another choice under its recovery/review policy, including a different provider. Leader and Implementer have their own ladders. Implementer can additionally use low, normal and high complexity ladders; an unspecified complexity ladder inherits its base ladder.

In .shikiru/config.toml, a rung can be written as a short string, "agent:model" or "agent:model:effort", or as an inline table, { agent, model, effort } (effort optional). Both forms can appear in one ladder, and existing table ladders keep loading unchanged:

[roles.leader]
ladder = ["codex:gpt-6.1-sol:high", { agent = "claude", model = "claude-sonnet-5-5" }]

The short form reads its third part as the effort, so a model or effort containing :, or an empty effort, must use the table form. A malformed short entry, or one with an empty part, fails config loading and names the entry. init and the wizard write the short form, and the table form for any rung the short form cannot express.

Rejected implementations return for another review iteration, with a possible Implementer rung increase. Provider unavailability gets bounded backoff/retries; quota can wait for a reset or move to a later different-provider rung when the configured wait budget is exhausted. Stalls receive limited continuation attempts. Authentication problems, unrecoverable failures and exhausted limits request Operator attention rather than silently completing a task.

Helper has a separate ordered ladder. It tries later entries after failed calls or unusable answers, within one total Helper timeout. Any rebuilt report must still pass validation; Helper neither approves work nor decides the workflow. Agent session resumption and compaction are provider-specific; automatic compaction thresholds are configurable per agent. Token counts, context, costs, billing mode and quota are shown when supplied by the agent; missing data stays unknown, and quota observations may be stale. A quota block is revalidated periodically in the background (and on an Operator retry) against newer provider readings, without delaying other tasks or commands, so queued work resumes when quota returns before the predicted reset. Quota reset times are shown in your local timezone. A task waiting on quota shows an amber ⧗ quota in its tmux window tab, and each agent pane affected by the wait shows a ⧗ Quota blocked · next check … (or retry …) strip above its output until the wait ends.

Configuration and automation

Settings merge in this order: packaged defaults → .shikiru/config.toml → repeated global --set key.path=value overrides for that invocation. Use the wizard for project choices and edit the config for additional controls. An already-running engine keeps the settings it started with; stop/start it to apply engine policy changes. When a new engine run starts, the dashboard re-reads the config for slot counts, gauge thresholds, briefing and timeline display, animations, the palette confirmation delay, and the disk, Docker and resource refresh intervals; timeouts, Docker scope, the repository status cache, the motion timer and the widget list apply when the dashboard starts. An invalid config keeps the last valid values and shows an alert in the header.

Integration: orchestration.integration = "merge" rebases and applies accepted work to the local base. "squash" ("Local squash and merge") lands the rebased task as a single commit parented by the current base and carrying the task's complete tree; an empty task adds no commit. It shares every local-merge guard. Task commits follow the target project's documented subject convention, or Conventional Commits when none is documented, and carry a Task: T-n trailer; merge preserves them, while squash uses the accepted whole-change subject and summary and adds the task ID and recovery trailers. The Result and Results of a completed task show the landed commit's SHA and subject, its destination and the integrated file and line totals, which stay accurate after the task branch and worktree are cleaned up. "pr" pushes the task branch, opens/adopts a GitHub PR and waits for it to merge; conflicting/closed/failed or overdue PRs require recovery or a decision. After a merge, the local base is fast-forwarded to the merged remote tip before the task is done. If it cannot be (local commits the remote lacks, or uncommitted changes in files the merge changes), the task escalates as integration blocked and leaves your work untouched; resolve it, then retry to finish the sync. Shikiru does not bypass repository review policy. With orchestration.pr_feedback = "changes_requested" (default) a newly submitted changes-requested review, or a new reply in one of its inline discussions, starts a feedback round. With "any_comment" a newly submitted review that has a body (commented, approved or changes requested) and a new reply in any inline discussion start one too. In the wizard the choice appears under Integration once "Pull request" is selected. A round works like this: the Leader analyses it, the Implementer edits, the Leader verifies, and the engine pushes with a lease and replies per item, then returns to the PR wait. Conversation comments, pending or dismissed reviews, Shikiru's own replies and edits to handled reviews never start rounds, and Shikiru never dismisses reviews, resolves threads, approves or merges. orchestration.max_iterations bounds attempts per batch. A PR closed without merge escalates and keeps the branch and worktree; only an explicit Operator retry opens a new PR. Dirty overlapping changes in the main checkout block local integration; commit, move or otherwise resolve them before retrying.

Pushes (merge and squash modes): orchestration.push_interval_seconds (default 14400, four hours; a nonnegative whole number of seconds) controls when locally integrated work reaches repo.remote. Integrations within an interval accumulate and the first one sets the deadline, so later ones do not postpone it. 0 pushes after each successful local integration. Only the base branch is pushed, never forced and never task branches or tags; a rejected or timed-out push raises an engine fault, keeps the work pending and retries with backoff. A remote that is not configured is not pushed to and raises no fault: the work stays pending and the remote is checked again after orchestration.remote_recheck_seconds (default 60, a positive whole number of seconds). A check that itself fails is a fault like a failed push: it is retried with the same backoff and recovers once the check succeeds. Pending work survives restarts. PR mode does not use this setting. Stop and restart the engine to load a changed value.

Caches: selected Git-ignored cache paths can be cloned into task worktrees using filesystem copy-on-write. If unsupported, Shikiru warns and leaves caches uncloned; it does not silently make an expensive ordinary copy. Trackers and caches are optional.

Notifications: tmux messages and an optional hook report completions, escalations, integration waits, lost takeovers and engine faults. Urgent undelivered notifications survive restarts; a crash can cause a duplicate delivery, so hooks should tolerate repeats.

Provider retry timing: [orchestration.retries] configures unavailable-agent retries in seconds, with a multiplier and maximum delay. Defaults are 30 seconds, multiplier 4, 300 seconds maximum and 3 retries (delays of 30, 120 and 300 seconds before ladder fallback). The retry count may be zero and is limited to 20. Stop and restart the engine to load changed values. These settings are separate from [orchestration.faults], which controls engine tick retries.

Automation and extensions: CLI JSON supports scripts. MCP exposes status/task/escalation queries (an escalation carries its packet plus parsed question, agent_options and resolutions), session peeks, submission, prioritization, pause/resume/cancel/retry, rung changes, messages, takeover/handback, escalation resolution and event waiting. It uses the same operator services and command queue as the dashboard. Agent and widget plugins use Python entry points; the agent contract, SDK and contract test kit support additional agents. A plugin opts into the wizard's Agents step by giving its agent a settings() method that returns AgentSetting entries (key, label, help, kind, default and bounds or choices); the plugin's own factory still validates the resulting options. It can raise AgentOptionsError with the rejected option key so the wizard focuses that field, or omit the key for an agent-wide rejection.

For exact fields and defaults, see defaults.toml, settings validation, Claude options and Codex options. The MCP tools provide the automation contract.

Persistence, diagnosis and safety

The engine is independent of the terminal. Restart it with shikiru start to reload persisted state, reconcile unfinished work and resume eligible tasks. Re-running start also ensures the project's tmux session. Terminal detach, engine stop, task pause and task cancellation are distinct operations: detaching changes only your connection; Stop interrupts engine-supervised turns and ends orchestration while preserving state and the tmux session. Start reconciles and resumes eligible work. Use task controls when you need to halt a specific task without stopping others.

Use Doctor for setup/state problems, status for progress and decisions, and dashboard Diagnostics for live resource/fault information. Retention removes eligible finished evidence after configured horizons while preserving unresolved work; export evidence you need to keep. Missing/corrupt state is not repaired by deleting .shikiru/. To roll back after a migration, stop the engine and copy the newest file from .shikiru/backups/ over state.db.

Shikiru orchestrates agents; it does not sandbox them. Agents run as your user, inherit their CLI's environment and may use your credentials. Use only repositories and hosts you trust.

• Claude Code defaults to --permission-mode bypassPermissions.
• Codex uses workspace-write, with the run directory, task worktree Git directory and shared repository .git writable. Agents can affect shared Git refs, hooks and configuration.
• Worktrees separate task files, but do not enforce isolation from the main checkout or other worktrees. Project instructions and notification commands also run with your privileges.
• State files are owner-only, not a security boundary against agents running as you. Prompts, reports and exports can contain project-sensitive content; review them before sharing.

Review changes and commits before trusting them. Agent review and a valid report are not proof that software is correct.

Shikiri-yaku

Shikiru stops and waits for a person when it raises an escalation. Shikiri-yaku is a companion background service that takes that seat: it watches the escalations of your Shikiru projects, handles the routine ones (retries, quota waits, engine restarts, approved tool installs) and forwards the rest to you in Telegram, where one tap applies the answer. It talks to Shikiru only through shikiru mcp and the CLI, and keeps nothing in your repositories. Its doctor checks that the installed Shikiru is compatible.

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to validate a checkout and a real project.

Design

Design explains the architecture and invariants. The retained CLI examples and dashboard reference show the interface direction.