Local-first Git workflow configuration for real repositories.

Koba is a local-first Git workflow configurator for real repositories. It helps you inspect workflow infrastructure, draft a repo workflow contract, run configured checks, connect hooks, generate PR templates, and prepare commit/PR text without taking over Git.

Koba is built around a simple safety model: read first, recommend next, preview writes, and apply only when explicitly requested.

• 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.
• Suggest Conventional Commit messages and safe Git commands.
• Draft a local PR title/body without opening a PR.

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 once releases are available.

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.

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 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.

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, 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.

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.

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, preview/apply flows, and tests that use temporary repositories instead of mutating the real workspace.