Local-first commit planning for real repositories.

Koba

Koba turns a messy working tree into clean commits.

Koba currently analyzes working trees, proposes coherent commit groups, recommends relevant checks, and suggests deterministic/path-driven Conventional Commit messages. Workflow inspection, configured checks, hooks, templates, and PR drafting remain useful supporting capabilities.

Important

The current release does not create commits yet; commit execution remains manual, and koba commit is not an available command. The commit-first direction permits future scoped staging and commit creation only after an exact preview and explicit user approval. The default commit flow will never push automatically or use broad staging such as git add ..

Koba is local-first. Deterministic code owns grouping, checks, risk, and mutation safety. Optional future AI may help describe an existing commit plan, but it will not decide grouping, mutation, or approval.

What Koba Can Do Today

• Inspect repository workflow files with scan.
• Diagnose missing or risky workflow setup with doctor.
• Preview or write a minimal koba.yml workflow contract.
• Run pre-commit and pre-push checks from koba.yml.
• Preview or install native Git hook and Husky hook files that call koba run.
• Preview or generate a GitHub pull request template.
• Review working-tree changes and plan surgical commits.
• Suggest Conventional Commit messages and safe Git commands.
• Draft a local PR title/body without opening a PR.

The planned primary flow is analysis -> commit groups -> descriptions -> preview -> checks -> explicit approval -> scoped staging and commit creation. That execution flow is roadmap work; the commands below document the current release.

Install

Koba is early MVP software. The CLI is useful for local dogfooding today, but the command surface and config schema may still change.

On Windows, install Koba with Scoop:

scoop bucket add postigodev https://github.com/postigodev/scoop-bucket
scoop install koba

Update or uninstall it with:

scoop update koba
scoop uninstall koba

You can also download prebuilt binaries from GitHub Releases.

For local development, install the CLI from this workspace:

cargo install --path crates/koba

Or run it directly from the workspace:

cargo run -p koba -- scan

See docs/distribution.md for the staged distribution plan.

Quickstart

From a Git repository:

koba scan
koba doctor
koba init
koba init --apply
koba run pre-commit --dry-run
koba hooks install --adapter native --dry-run
koba github template pr --dry-run
koba changes
koba suggest-commit
koba pr --dry-run

The default mode for generators is preview-only. Commands such as init, hooks install, github template pr, and pr only write files when passed --apply, and they refuse to overwrite existing user files.

Agent Skill

Koba includes a skills.sh-discoverable Agent Skill that teaches coding agents such as Codex and Claude Code how to use the koba CLI safely for repository inspection, working-tree review, surgical commits, and PR preparation.

npx skills add postigodev/koba --skill koba --global --agent codex --agent claude-code --yes

Example prompt:

Prepare a surgical commit using Koba, but do not stage or commit until I approve.

See docs/agents.md for installation, approval boundaries, and skills.sh details.

Commands

Command	What it does	Writes files?
koba scan	Shows what workflow infrastructure exists.	No
koba doctor	Interprets scan results into diagnostics and next steps.	No
koba init	Prints a proposed koba.yml.	No
koba init --apply	Writes koba.yml if it does not already exist.	Yes
koba run pre-commit	Runs checks.preCommit from koba.yml.	No
koba run pre-push	Runs checks.prePush from koba.yml.	No
koba run <stage> --dry-run	Lists checks without executing them.	No
koba changes	Reviews working-tree changes, suggests commit groups, and recommends checks.	No
koba hooks install --adapter native	Previews native hook files for .git/hooks/.	No
koba hooks install --adapter native --apply	Writes missing native hook files.	Yes
koba hooks install --adapter husky	Previews Husky hook files for .husky/.	No
koba hooks install --adapter husky --apply	Writes missing Husky hook files.	Yes
koba github template pr	Previews .github/pull_request_template.md.	No
koba github template pr --apply	Writes the PR template if it does not already exist.	Yes
koba suggest-commit	Suggests a Conventional Commit message and Git commands.	No
koba pr	Previews a PR title and body from local Git state.	No
koba pr --apply	Writes .koba/pr-body.md if it does not already exist.	Yes

Example koba.yml

version: 1
profile: rust-cli

commits:
  convention: conventional
  requireScope: true

checks:
  preCommit:
    - cargo fmt --check
  prePush:
    - cargo test

koba run pre-commit executes each command under checks.preCommit. koba run pre-push executes each command under checks.prePush. For now, checks are simple shell commands.

Development

Run the scoped checks:

cargo fmt --check
cargo check -p koba
cargo test -p koba
git diff --check

Koba is intentionally conservative. When adding new behavior, prefer structured results, exact previews, explicit approval, scoped mutation, and tests that use temporary repositories instead of mutating the real workspace. Never add automatic push to the default commit flow.