Kroker

Spec-first, vendor-agnostic control plane for agent-driven software development

Features • Quick Start • Documentation • Architecture • Contributing

Kroker enables engineering teams to design, execute, and govern LLM-powered development workflows without surrendering control to any single model, vendor, or proprietary toolchain.

┌─────────────────────────────────────────────────────────────┐
│ Kroker: Agent Execution with Governance                     │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Spec → Isolated Worktree → Agent Runs → Gates Pass         │
│                                   │                          │
│                                   └─→ Bundle (Provenance)   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Why Kroker?

Agent-driven development introduces process fragility—unreproducible runs, unchecked code changes, and no provenance for decisions. Kroker solves this by wrapping every agent run in:

Isolated git worktrees - Every run executes in isolation, no risk to your main branch
Configurable quality gates - Tests, linters, security scans must pass before changes surface
Cryptographic provenance - Complete audit trail with replayable run artifacts
Vendor independence - Works with Claude Code, OpenCode, Copilot CLI, or custom tools

Quick Start

Installation

macOS (Homebrew)

brew tap Kit-Kroker/homebrew-kroker
brew install kroker

macOS/Linux (Go)

go install github.com/Kit-Kroker/Kroker/cmd/kroker@latest

macOS/Linux/Windows (Direct Download)

Download from GitHub Releases
Extract and add to $PATH

Usage

# Verify installation
kroker --version

# Generate a spec using AI
kroker spec generate "add redis caching to user service"

# Create a spec interactively
kroker spec create

# Lint a spec
kroker spec lint sdd-spec.yaml

# Run an agent with gates
kroker run sdd-spec.yaml --agent claude-code

# View the diff from a completed run
kroker view <run-id>

# Launch interactive TUI
kroker tui

Viewing Agent Changes

After running an agent, you can view the changes made using the kroker view command:

# View the diff from a completed run
kroker view <run-id>

# View with color disabled (for piping to files)
kroker view <run-id> --no-color > diff.patch

# View in system pager (for large diffs)
kroker view <run-id> --pager

View Command Features:

Colorized output - Additions in green, deletions in red, hunk headers in cyan
No-color mode - Disable ANSI codes for piping to files or scripts
Pager support - Use less or more for viewing large diffs comfortably
Graceful error handling - Clear messages for missing runs or empty diffs

Exporting Artifacts

After running an agent, you can export changes in two formats:

Exporting Patches

Export just the code changes as a patch file for manual review or application:

# Export patch from a completed run (default filename: sdd-<run-id>.patch)
kroker export <run-id>

# Export to custom location
kroker export <run-id> --output /tmp/my-changes.patch

# Export with -o shorthand
kroker export <run-id> -o changes.patch

Applying Patch:

# Review patch file
cat sdd-<run-id>.patch

# Apply patch to your codebase
git apply sdd-<run-id>.patch

# Check what changed
git status

Accepting Changes

After reviewing changes from a successful run, you can apply them directly to your working directory using the kroker accept command:

Basic Usage

# Accept changes from a completed run
$ kroker accept kroker-20260131-143055-feature-1

Output:
Validating run kroker-20260131-143055-feature-1 for acceptance...
Loading diff from run bundle...
Detecting conflicts...
Applying patch...
Changes applied successfully:
  Files modified: 3
  Lines added: 15
  Lines deleted: 5

Next steps:
  1. Review changes: git diff
  2. Commit changes: git commit
  3. Or use 'kroker accept <run-id> --commit' (Story 5.2)

Auto-Commit with --commit Flag

Automatically create a git commit with run metadata and verification trailers when accepting changes:

# Accept changes and create commit in one step
$ kroker accept kroker-20260131-143055-feature-1 --commit

Output:
Validating run kroker-20260131-143055-feature-1 for acceptance...
Loading diff from run bundle...
Detecting conflicts...
Applying patch...
Changes applied successfully:
  Files modified: 3
  Lines added: 15
  Lines deleted: 5

Extracting spec hash from run bundle...
Generating commit message with run metadata...
Commit created: abc1234def56789
Files committed: 3

Commit Message Format:

The generated commit message follows this structure:

[kroker] Run Summary

Run Description (from spec.yaml)

kroker-run-id: kroker-20260131-143055-feature-1
kroker-spec-hash: a1b2c3d4e5f6
Signed-off-by: kroker <kroker-20260131-143055-feature-1>

Commit Flags:

--commit - Create a git commit after applying changes (default: false)
--amend - Amend the previous commit instead of creating new one (default: false)
--no-verify - Skip git pre-commit and commit-msg hooks (default: false)

Verification Trailers (FR27):

Each auto-created commit includes:

kroker-run-id - The run identifier for traceability
kroker-spec-hash - First 12 characters of the spec's SHA-256 hash
Signed-off-by - Kroker signature with run ID

FR26 Compliance:

The commit automatically squashes all applied changes into a single git commit, providing clean history.

Dry Run Mode

Preview what would be applied without making any actual changes:

# Preview changes without applying
$ kroker accept kroker-20260131-143055-feature-1 --dry-run

Output:
Dry run complete (no changes applied):
  Files that would be modified: 3
  Lines added: 15
  Lines deleted: 5

Force Accept

Bypass working directory checks when you know it's safe:

# Force accept (bypass working directory check)
$ kroker accept kroker-20260131-143055-feature-1 --force

Note: Use --force carefully - it bypasses safety checks but will still
reject merge conflicts which are always unsafe.

Verbose Output

Show detailed output during acceptance:

$ kroker accept kroker-20260131-143055-feature-1 --verbose

Output:
Validating run kroker-20260131-143055-feature-1...
  ✓ Run bundle exists: .kroker/runs/kroker-20260131-143055-feature-1
  ✓ Diff file exists: changes.diff
  ✓ Event log is intact
  ✓ Working directory is clean
Loading diff from run bundle...
  ✓ Parsed 3 file changes
  ✓ Additions: 15, Deletions: 5
Detecting conflicts...
  ✓ No merge conflicts detected
Applying patch...
  ✓ Backup created: /tmp/kroker-backup-1738317455
  ✓ Patch check passed
  ✓ Applied patch with 3-way merge
  ✓ Files modified: internal/accept/apply.go, cmd/kroker/accept.go, README.md
Verifying application...
  ✓ All files from diff were applied
  ✓ No rejected files
  ✓ No merge conflicts introduced
  ✓ Cleanup: Backup removed
Changes applied successfully!

Note: Gate validation and scope checking are partially implemented in current version.
Full gate/scope validation will be added in future releases.

Error Handling Examples

# Attempt to accept a run that failed gates
$ kroker accept kroker-20260131-120000-feature-2

Error: Run kroker-20260131-120000-feature-2 is not eligible for acceptance:
  - Run status is Failed, only Success runs can be accepted
  - Required gate 'tests' failed

# Attempt to accept with conflicts
$ kroker accept kroker-20260131-143055-feature-1

Error: Cannot accept: blocking conflicts detected
  - Merge conflict markers found in: src/main.go

Fix merge conflicts before accepting, or use '--force' to bypass (unsafe for merge conflicts).

Accept Command Features:

Validation - Only runs that completed successfully and passed all gates can be accepted
Conflict detection - Checks for uncommitted changes, local modifications, and merge conflicts
Dry-run mode - Preview what would be applied without making changes
Safe patching - Uses git apply --3way for reliable patch application
Automatic rollback - If patch application fails, automatically restores from backup
Event logging - All acceptance operations are logged for audit trail
Verbose output - Detailed progress information for troubleshooting

Acceptance Requirements:

Run must have completed successfully (status = Success)
All required quality gates must have passed
No unhandled scope violations (or violations were overridden with logged reason)
Working directory should be clean (use --force to bypass this check)

Next Steps After Accepting:

Review the applied changes: git diff
Commit the changes: git commit -m "Description of changes"
Push to remote: git push

TUI Integration: You can also accept runs directly from the Kroker TUI by pressing a when a successful run is selected. The TUI provides the same validation and conflict detection with an interactive confirmation dialog.

Exporting Bundles

Export the entire run bundle including all artifacts for sharing or archival:

# Export bundle from a completed run (default filename: sdd-bundle-<run-id>.tar.gz)
kroker export <run-id> --format bundle

# Export bundle to custom location
kroker export <run-id> --format bundle --output /tmp/my-bundle.tar.gz

# Export bundle with -o shorthand
kroker export <run-id> --format bundle -o bundle.tar.gz

Extracting Bundle:

# Review bundle file
tar -tzf sdd-bundle-<run-id>.tar.gz

# Extract bundle contents
tar -xzf sdd-bundle-<run-id>.tar.gz

# Navigate to extracted run
cd <run-id>

# View spec, events, diff, etc.
ls

Export Command Features:

Standard patch format - Compatible with git apply (unified diff format)
Bundle format - Complete run bundle with spec, events, diff, and gates (tar.gz archive)
Custom output path - Specify where to save the export file
Format selection - Choose between patch (default) and bundle formats
Git apply compatible - Generated patches can be applied to any git repository

Patch Format Details:

Uses standard unified diff format (compatible with git diff --unified)
Can be applied with git apply, patch, or other diff tools
Includes complete context for hunk application
Suitable for code review and manual application workflows

Bundle Format Details:

Standard tar.gz archive format (compatible with tar, gzip, gunzip, 7-Zip, WinRAR)
Contains complete run bundle directory with all artifacts
Preserves directory structure and file permissions
Includes spec.yaml, events.jsonl, changes.diff, agent.log, gates/, and metadata.json
Suitable for sharing full context, archival, and transfer between systems

TUI Interface

Kroker provides a terminal user interface (TUI) for interactive run monitoring and project management. Launch it with:

# Launch the TUI
kroker tui

TUI Features:

Live Run Monitoring

Real-time log streaming - Watch agent output live as it happens in the main view
Run status indicators - Visual status icons (🟡 pending, 🔵 running, ✅ success, ❌ failed, ⚪ cancelled)
Automatic refresh - Run list updates every 2 seconds to show current status
Manual refresh - Press R to manually refresh the run list
Log buffer preservation - Logs persist after run completion for review

File Browser + Viewer

Scope-aware file tree - Tag files as in-scope or out-of-scope for the active spec
Syntax-highlighted preview - Read files with line numbers and language detection
Filter modes - All files, in-scope only, or modified files from git status

Terminal Panel

Embedded shell - Run commands without leaving the TUI
Autocomplete + history - Tab suggestions and up/down history navigation
Visual blocks - Commands and output grouped with exit status and timing

Multi-Pane Layout

Header - Workspace, git, and time context
Sidebar - View navigation (Dashboard, Specs, Runs, Files, Agents, Git, Tasks, Settings)
Main View - Details, previews, and live logs
Inspector - Context detail panel on wide terminals
Terminal Panel - Toggleable bottom panel for command execution
Footer - Status messages and keyboard hints

Keyboard Navigation

Global Shortcuts:

1–8 - Switch between Dashboard, Specs, Runs, Files, Agents, Git, Tasks, Settings
Tab / Shift+Tab - Cycle focus between sidebar, main, inspector, terminal
` - Toggle the terminal panel
Ctrl+P - Open project setup modal
a - Accept selected successful run
s - Stop the active run
q or Ctrl+c - Quit the TUI

Runs View:

j / k or ↑ / ↓ - Navigate runs
Enter - Select a run and view details
r - Filter active runs (or open recovery for failed run)
f - Filter failed runs
/ - Search/filter runs
R - Manually refresh the run list

Log View (active run):

j / ↓ - Scroll down one line
k / ↑ - Scroll up one line
d / Ctrl+d - Scroll down one page
u / Ctrl+u - Scroll up one page
g - Jump to top of logs
G - Jump to bottom of logs
f - Toggle auto-scroll (follow new lines)

Terminal Panel:

Enter - Execute command
Tab - Cycle autocomplete suggestions
↑ / ↓ - Navigate command history
Ctrl+C - Interrupt running command
PgUp / PgDn or j / k - Scroll terminal output

Responsive Design

Adapts to terminal resize automatically
Sidebar collapses to icon-only under 100 columns
Inspector hides on narrower terminals
Graceful degradation on smaller terminals

Minimum Requirements

Terminal size: 80x24 (minimum)
Colors: 256-color terminal recommended (graceful degradation otherwise)

Memory Management

Ring buffer with 1000-line capacity for logs
Memory usage stays bounded (~100KB per log buffer)
Old log lines automatically evicted when capacity is reached

Bundle Use Cases:

Sharing with colleagues - Send complete context including spec and events
Archival - Save full run artifacts for future reference
Transfer between systems - Move runs between machines or environments
Debugging - Provide complete reproducible context for troubleshooting

Features

Local-First, Vendor-Agnostic

No vendor lock-in - Switch between Claude Code, OpenCode, Copilot CLI, or custom tools
Single binary - No runtime dependencies, no cloud services required
Your tools, your rules - Bring your own agent tools and quality gates

Process Governance

Quality gates - Run tests, linters, security scans before accepting changes
Scope control - Restrict which files agents can modify with glob patterns
Audit trail - Append-only event log tracks every action

Reproducible Runs

Run bundles - Complete artifacts containing spec, agent output, gates, and diffs
Cryptographic hashing - Tamper-proof provenance for every run
Replay capability - Understand what happened and why

Developer Experience

TUI interface - Terminal UI with split-panes, keyboard navigation, real-time progress
CLI commands - Scriptable commands for automation and CI/CD integration
Clear error messages - Actionable guidance when things go wrong

Example Spec

version: 1
name: add-user-authentication
description: Add JWT-based authentication to API

agent:
  tool: claude-code
  prompt: |
    Add JWT-based authentication to the user API.
    - Create middleware for token validation
    - Add login/logout endpoints
    - Update existing routes to require auth

scope:
  allowed_paths:
    - "internal/auth/**"
    - "internal/api/**"
  forbidden_paths:
    - "internal/config/**"
    - "**/test/**"

gates:
  - name: tests
    command: go test ./...
    timeout: 5m
  - name: lint
    command: golangci-lint run
    timeout: 2m
  - name: security
    command: gosec ./...
    timeout: 1m

Technology Stack

Core Technologies

Go 1.23+

Git Worktrees

YAML Specs

Key Libraries

Library	Purpose	Version
Cobra	CLI framework	1.8.0
Bubble Tea	Terminal UI	1.3.4
Lipgloss	Terminal styling	1.1.0
Viper	Configuration	1.18.0
Playwright	E2E testing	1.49.0

See ARCHITECTURE.md for detailed technical information.

Architecture

Kroker uses a layered architecture with isolated execution environments

flowchart LR
    Spec[Spec YAML] --> Worktree[Git Worktree]
    Worktree --> Agent[Agent Tool]
    Agent --> Gates[Quality Gates]
    Gates --> Bundle[Run Bundle]
    Bundle --> Review[Review/Export]

Documentation

Full documentation is available at https://maksim.github.io/kroker (update with your actual URL).

TODO App Tutorial - Build a complete TODO application step-by-step
Getting Started
User Guide
Developer Guide
CLI Reference

Development Status

Kroker is under active development. Current status:

Component	Status
Config System	✅ Complete
Spec Management	✅ Complete
Worktree Isolation	✅ Complete
Agent Orchestration	✅ Complete
Run Bundles	✅ Complete
TUI Interface	🟡 In Progress
Gates Execution	🟡 In Progress

See docs/index.md for detailed implementation status.

Contributing

Contributions are welcome! Please see our Contributing Guide for:

Code style guidelines
Development setup
Testing requirements
Pull request process

Use Cases

Safe Hotfixes (Elena - Senior Engineer)

Run agent-driven hotfixes in isolated worktrees with quality gates, ensuring nothing breaks before merging.

No Vendor Lock-in (Marcus - Infrastructure Engineer)

Local-first tool that works with any agent, no API keys to manage, no cloud dependencies.

Guided Development (Jamie - Junior Developer)

Constrained templates prevent mistakes by restricting which files can be modified.

Self-Evident PRs (Sophia - Code Reviewer)

Run bundles provide complete context, making code reviews faster and more thorough.

Testing

Kroker has comprehensive test coverage:

Unit Tests - >80% code coverage target
Integration Tests - Cross-component workflow validation
E2E Tests - Full user journey testing with Playwright

# Run all tests
make test-all

# Run by test type
go test ./...                    # Unit tests
go test ./tests/integration/...  # Integration tests
cd tests && npm run test:e2e:p1  # E2E tests (P0-P1)

See TESTING.md for comprehensive testing documentation.

Release Status

Current version: v0.0.1 (Initial Release)

Component	Status
Config System	✅ Complete
Spec Management	✅ Complete
Worktree Isolation	✅ Complete
Agent Orchestration	✅ Complete
Run Bundles	✅ Complete
TUI Interface	🟡 In Progress
Gates Execution	🟡 In Progress

See CHANGELOG.md for version history and docs/index.md for detailed implementation status.

License

MIT License - see LICENSE for details

Support

Documentation: https://maksim.github.io/kroker
Issues: GitHub Issues
Discussions: GitHub Discussions

Built with ❤️ by Maksim

Name		Name	Last commit message	Last commit date
Latest commit History 304 Commits
.github/workflows		.github/workflows
.specify		.specify
.vscode		.vscode
bin		bin
cmd/kroker		cmd/kroker
docs		docs
internal		internal
scripts		scripts
specs		specs
templates		templates
tests		tests
tools/gates		tools/gates
.env.example		.env.example
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
.nvmrc		.nvmrc
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
HOMEBREW_SETUP.md		HOMEBREW_SETUP.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
RELEASE_CHECKLIST.md		RELEASE_CHECKLIST.md
SECURITY.md		SECURITY.md
TESTING.md		TESTING.md
go.mod		go.mod
go.sum		go.sum
homebrew-kroker-formula.rb		homebrew-kroker-formula.rb
kroker-test		kroker-test
mkdocs.yml		mkdocs.yml
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
requirements.txt		requirements.txt
test-override.yaml		test-override.yaml

Folders and files

Latest commit

History

Repository files navigation

Kroker

Why Kroker?

Quick Start

Installation

Usage

Viewing Agent Changes

Exporting Artifacts

Exporting Patches

Accepting Changes

Basic Usage

Auto-Commit with --commit Flag

Dry Run Mode

Force Accept

Verbose Output

Error Handling Examples

Exporting Bundles

TUI Interface

Live Run Monitoring

File Browser + Viewer

Terminal Panel

Multi-Pane Layout

Keyboard Navigation

Responsive Design

Minimum Requirements

Memory Management

Features

Local-First, Vendor-Agnostic

Process Governance

Reproducible Runs

Developer Experience

Example Spec

Technology Stack

Core Technologies

Key Libraries

Architecture

Documentation

Development Status

Contributing

Use Cases

Safe Hotfixes (Elena - Senior Engineer)

No Vendor Lock-in (Marcus - Infrastructure Engineer)

Guided Development (Jamie - Junior Developer)

Self-Evident PRs (Sophia - Code Reviewer)

Testing

Release Status

License

Support

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages