@banhosdev/kimo-init

A local Task + Library + Agent Skills framework for any agent CLI. No Kimo desktop account or source clone is required. OpenSpec and GSD can coexist.

Install

Requires Node.js 22+ and Git. Installed Task/worktree helpers also require Python 3; the installer itself does not.

npx @banhosdev/kimo-init@latest . --name "My Project" --prefix PROJ
npx @banhosdev/kimo-init@latest . --name "My Project" --prefix PROJ --apply

Preview is the default. The target defaults to the current directory and must be a Git repository root. Use --help or --version. For reproducibility, replace @latest with @0.5.0.

The CLI installs twelve .agents/skills/kimo-* Skills, Task/subtask templates, project context and a free-form Library. Worktrees/runtime live under .kimo/ and are ignored by Git. It does not modify application code, add project dependencies, start services or initialize/clone a database.

Select your agent CLIs

.agents/skills is always installed. Select additional entry points with a comma-separated list:

npx @banhosdev/kimo-init@latest . --name "My Project" --prefix PROJ --clis codex,claude,verboo --apply
npx @banhosdev/kimo-init@latest . --update --clis all --apply

• codex: uses the canonical .agents/skills and AGENTS.md already included.
• claude: adds project entry Skills under .claude/skills.
• verboo: adds project entry Skills under .verboo/skills.
• all: selects all three; none: only the shared .agents base.

The default is Codex/shared base for a new or legacy installation; later updates reuse your recorded selection. Entry Skills point to the canonical .agents procedures, including their reference files, so project customization has one place to live. These options install framework integration files, not CLI binaries or account credentials. Existing CLI settings and unrelated Skills are preserved. Removing a target from the selection does not delete its old files; they are left untouched and no longer synchronized until selected again.

Project Skill conventions: Claude Code, Verboo Code.

Personalize with your agent

After installing, tell your agent: "Read AGENTS.md and run kimo-init to understand and personalize this project." The installer copies files; the Skill conducts the conversation.

Init discovers current code/docs/design and asks only missing questions about product intent, domain, UI, development environment and workflow preferences. It consolidates authoritative knowledge, preserves existing docs and records gaps. It adapts to new projects, established codebases and later refreshes. It produces or updates a base of Product Definition, Design/UX, Architecture, Coding Conventions and Development/Validation documents, plus a reading map. Existing authoritative Docs can fulfill these roles. No fixed folder taxonomy or automatic mass-import of OpenSpec/GSD history.

The main workflow is:

Init → Create Task (includes shaping) → review/authorization → Execute → Close Task

Close includes review, criterion/subtask verification, Result and Library reconciliation before done. Shape remains for refining existing Tasks, Review for isolated reviews. UI guidance includes layout, interactions, states, responsiveness, accessibility and rendered verification. Optional template sections are chosen by need. Maintain Library includes a document template, a decision-record variant and a catalog of base documents, domain/integration references, runbooks and research, with rules for when to update or create each.

Agent CLIs without Skill discovery can read the relevant SKILL.md explicitly. A helper creates a Task shell; the agent fills it and removes unused template sections:

python3 .agents/skills/kimo-create-task/scripts/new_task.py "Add checkout validation"

Update an installed project

npx @banhosdev/kimo-init@latest . --update
npx @banhosdev/kimo-init@latest . --update --apply

The installer remembers the project name/prefix in .kimo/framework.json. Version 0.1.0 installations are recognized from their marked AGENTS section, with name/prefix inferred from .kimo/project.md; provide those flags if absent. The bundled historical baseline identifies unchanged old framework files. Desktop-mode Kimo repositories are not converted into standalone mode by update.

• Unchanged framework Skills, references, templates and the framework README can update.
• Project context, Library content, historical Tasks and unrelated files are always preserved. New onboarding should update project knowledge through the agent, not by overwriting it with installer defaults.
• Only the marked framework section of AGENTS.md is managed; surrounding instructions remain intact. Local edits inside the section require reconciliation.
• New missing files are created. Plain reinstall without --update fills missing files and preserves existing ones; use --update to upgrade their content.
• No automatic deletion of obsolete/custom files or downgrade of recorded package versions.

Local changes and conflicts

If a managed file differs from its baseline, update exits 2 and does not apply any framework update. With --apply, it writes proposed versions under the ignored .kimo/runtime/framework-updates/ directory for comparison. Inspect the printed proposal path and use your editor/diff tool to merge the relevant changes.

After manually adopting/merging changes, rerun the preview. An exact match to the proposed version is adopted automatically. To deliberately retain a customized file (including a manually merged version that differs from the proposal), specify it explicitly:

npx @banhosdev/kimo-init@latest . --update --accept-local .agents/skills/kimo-create-task/SKILL.md
npx @banhosdev/kimo-init@latest . --update --accept-local .agents/skills/kimo-create-task/SKILL.md --apply

Repeat --accept-local for each reviewed path. This keeps the whole local file; it is not an automatic semantic merge. The decision is remembered for this vendor version. A later vendor change or new local edit requires review again. Never blindly copy an entire proposal directory over your project.

Backups and recovery

Before changes, the CLI saves original files and a journal under .kimo/runtime/framework-backups/<version>-<id>/. Keep .kimo/framework.json versioned; runtime backups/proposals stay local and may contain your local instructions. Baselines identify framework ownership, not desktop Project identity.

Writes are serialized by an operation lock and existing-file replacement is atomic. The state record is saved last; if interrupted, investigate the lock and rerun after confirming no operation is active. Already-updated files are recognized. A caught failure rolls back this operation's writes when they have not been modified concurrently. Always inspect the reported backup on failure.

For manual recovery, inspect journal.json, restore the corresponding original/ files (including the prior framework state), and remove only newly-created paths listed there after verifying they still belong to the failed update. Preserve subsequent user edits. Do not delete the entire runtime or use a blanket reset.

Maintainers

The package has no npm runtime dependencies or install hooks. Source Skills/templates and scripts/dogfooding/install.py generate assets/framework.json via build_npm.py. The frozen assets/legacy-0.1.0.json supplies the migration baseline; never regenerate it from current templates.

From the Kimo repository root:

npm run build --prefix scripts/dogfooding/npm
npm test --prefix scripts/dogfooding/npm
python3 scripts/dogfooding/test_npm_package.py --output-directory scripts/dogfooding/.release
npm publish scripts/dogfooding/.release/banhosdev-kimo-init-0.5.0.tgz --access public

Publish the exact tested tarball. The pack test inspects the archive and runs npm exec offline for install and migration with Python absent from installer PATH. Do not package project knowledge, credentials, history, runtime or desktop code. Bump the version for each release. License remains UNLICENSED.

Personalized executable worktree environments (0.3.0)

Tell your agent to run kimo-init and configure worktree environments for this project. Init discovers existing tooling, asks enable/decline and missing startup/port/env/database choices, then authors project-owned .kimo/workspace.json and optional .kimo/hooks/ adapters. It validates configuration without starting services or cloning data. Updates preserve these files.

The standard environment.py helper runs on Python 3.10+ and macOS/Linux. It consumes the Task JSON record from the existing standalone or desktop Git helper. It supports read-only check/plan, prepare, start, status, stop and separate resource cleanup. Mutation commands preview unless --apply is supplied. Stop keeps the database and other data; Git removal remains separately gated.

python3 .agents/skills/kimo-manage-worktree/scripts/environment.py check --project .
python3 .agents/skills/kimo-manage-worktree/scripts/environment.py prepare --record .kimo/runtime/PROJ-001.json --apply
python3 .agents/skills/kimo-manage-worktree/scripts/environment.py start --record .kimo/runtime/PROJ-001.json --apply
python3 .agents/skills/kimo-manage-worktree/scripts/environment.py status --record .kimo/runtime/PROJ-001.json
python3 .agents/skills/kimo-manage-worktree/scripts/environment.py stop --record .kimo/runtime/PROJ-001.json --apply

Use the actual Task ID and record location. Commit the reviewed project profile/hooks before creating a new worktree so it receives them. Already active worktrees are not silently reconfigured by an installer update.

Configuration provides foreground service commands, HTTP checks, named ports, explicit env copies and resumable project preparation/cleanup hooks. Database cloning is performed by the project's reviewed adapter, with a selected local source and isolated destination; this is not a universal database engine implementation. Profiles document service gaps such as queues/uploads/external integrations. See the installed Skill's references/profile.md for the schema, safety contract and recovery instructions.

Close Task now resolves local merge, PR or keeping the branch, including the target branch/remote, using existing choices or a concise question round. Init can remember delivery preferences. A PR deliverable records its URL and pending review; opening one never silently merges it.

Before implementation, Create/Execute resolve current branch, a new branch in the checkout, or an isolated worktree plus base ref, reusing existing choices. New branches follow feat/fix/refactor/docs/test/chore/perf/build/ci/style conventions; helpers accept --type and --branch. Existing branches remain unchanged. Execute uses small coherent commits, stages only Task-owned changes and validates relevant behavior.

After merge/PR/retained-branch delivery, Close asks whether to keep or clean a separate workspace when the choice is unresolved. Cleanup after a PR can explicitly retain the committed unmerged branch with --keep-branch; it still requires verified inactivity, clean work and data reconciliation. The current checkout is never removed.

Review an existing PR (0.4.0)

Ask your agent: "Use kimo-review-pr to review and report the findings here." No Kimo Task or onboarding is required for a PR review. A linked Task/Library supplies additional context when available.

The Skill identifies the repository and base/head commits, inspects the diff and related code, checks CI and performs relevant local validation. It reports actionable findings by severity, location, trigger, impact and correction guidance, with validation limits. UI changes include relevant design/interaction checks.

Task Review, PR Review and Close share review criteria. Close can reuse matching PR evidence while checking the remaining Task criteria and Library updates. New commits or changed base/context require reconciliation. Remote comments, approval or requests for changes happen only when explicitly requested; a review does not merge the PR.

Existing installations receive the new Skill and references through --update, including entries for the remembered CLI selections. Project-owned Task/Library/environment files remain intact; customized framework instructions still require conflict resolution.

Local multi-agent execution (0.5.0)

Ask your agent to configure Kimo orchestration, then use "Run kimo-execute-task TASK-042 in orchestrated mode" or "Use kimo-orchestrate-task TASK-042". Direct execution remains available for small Tasks. Create still includes shaping; orchestration begins once intent is clear.

Project-owned .kimo/orchestration.json selects Planner, Worker and Reviewer CLIs/models, named check commands, maximum workers (default 3), repair rounds (default 2) and optional worktree environment preparation. Initial supported flow: Codex Planner → parallel Verboo/DeepSeek Workers → integrated Codex Review → bounded repair → final checks → existing Close/Library/delivery. Codex, Verboo, Claude and custom structured command adapters share the same scheduler contracts; models/authentication remain in the project's CLI configuration.

The bundled Python helper schedules dependencies, creates isolated worker branches/worktrees, passes prerequisite results and integrated code, verifies scoped changes, merges serially and records progress/results. Runtime state and private logs stay under .kimo/runtime/<TASK>-orchestration/. Workers are execution parts of one Task. It supports preview, status, scoped stop and resume. Invalid output, failed checks, permissions/auth errors, interrupted runs, conflicts and exhausted repairs preserve work and require attention instead of claiming completion.

See the installed kimo-orchestrate-task Skill and references/orchestration.md for profile/contracts and recovery. Requires Python 3.10+, Git, macOS/Linux and the chosen authenticated local CLIs; no desktop, server or API keys stored by Kimo. The installer never launches agents and updates preserve project orchestration/workspace profiles. Worktrees isolate edits but are not a security sandbox; use trusted commands and each CLI's permission controls.

The helper's ready_for_close is evidence, not Task done or publication. The invoking Skill continues through Close, verifies remaining criteria, reconciles Library and performs the chosen merge/PR/retention. Worker cleanup precedes parent workspace cleanup; data, process identity and dirty work are checked. No automatic branch deletion or permission bypass.