Harness Kit

July 14, 2026 · View on GitHub

Human + AI task orchestration that compounds. A kit for building with AI agents — orchestration, TDD-first execution, structured debugging, knowledge compounding, and cost-aware delegation. Each run makes the next one better.

Table of Contents

  1. Prerequisites
  2. Clone the Repository
  3. Run Local Setup
  4. Create Your First Board
  5. Create Your First Spec
  6. Generate Tasks with Odin
  7. Monitor Task Execution
  8. Spec Details
  9. View Generated Output
  10. Troubleshooting

1. Prerequisites

RequirementVersionNotes
Gitany
Python3.10+
Node.js18+
Claude Code or CodexlatestAt least one AI agent must be installed

No AI agent = Odin won't run. Install Claude Code CLI at claude.ai/code before continuing.

2. Clone the Repository

git clone https://github.com/deepklarity/harness-kit.git
cd harness-kit

3. Run Local Setup

From the root of the harness-kit repository, start all services:

./dev.sh

Wait until you see this line in the terminal:

→ Open http://localhost:9200

That means all three services started successfully:

ServicePort
Django backend9100
React frontend9200
Celery worker— (async task execution)

./dev.sh stays running in the foreground. Open a new terminal for the next step.

Install the Odin CLI

In the new terminal, navigate into the odin directory inside your clone:

Recommended (if you have pipx):

cd /path/to/harness-kit/odin
pipx install -e .

If you don't have pipx, install it first:

  • macOS: brew install pipx
  • Ubuntu/Debian: sudo apt install pipx
  • Windows: pip install pipx (then add ~/.local/bin to your PATH)

Alternative (using pip, no extra tools needed):

cd /path/to/harness-kit/odin
pip install -e .

4. Create Your First Board

Open the frontend and set up a board:

  1. Go to http://localhost:9200

  2. The "Create New Board" dialog appears automatically on first launch. You can also click create board from the board selector.

    Create board dialog

  3. Fill in the details:

    • Board Name: Pomodoro
    • Project Directory: Choose a location (you can create a new directory here or use an existing one)

    alt text

  4. Enable All Agents — select the agent you want to use.

    Enable agents dialog

  5. Click "Create Board"

5. Create Your First Spec

A specification (spec) is a markdown file that describes what you want Odin to build.

  1. Open a new terminal and navigate to your project directory:

    cd /path/to/pomodoro

  2. Copy the sample Pomodoro spec from the repository:

    cp /path/to/harness-kit/odin/sample_specs/web/apps/pomodoro_timer.md spec.md

    Spec file

The spec is now in your project directory. Odin will read it to generate tasks.

6. Generate Tasks with Odin

Make sure you are in your project directory:

cd /path/to/pomodoro

Auto Mode

odin plan spec.md --quick --auto
FlagDescription
--quickSkips codebase exploration
--autoRuns the planner automatically without interactive input

The command runs in the foreground and prints progress as it goes. Once it finishes, tasks are created on the board and execution begins automatically.

Odin plan CLI

Odin plan tasks

Interactive Mode

Interactive mode lets you review and refine the plan before execution starts:

odin plan spec.md

Interactive session

Step 1 — Generate initial plan

Press Enter to let the agent generate the initial plan.

Interactive session planning

Step 2 — Iterate on the plan

Ask the agent to revise or extend the plan. For example:

Add another task to export the session log as a CSV file.

Iteration planning

Press Enter and Odin will update the plan. Repeat until satisfied.

Step 3 — Exit

Press Ctrl+C twice to exit. Tasks will be created on the board.

7. Monitor Task Execution

Open the board at http://localhost:9200/board

You will see tasks created from the spec appearing on the board. Each task shows:

FieldDescription
Task nameWhat the agent is working on
StatusTODO, IN_PROGRESS, or DONE
Assigned agentWhich model is handling the task
Execution progressLive updates during a run

Tasks may take a few minutes each. The board updates in real time — leave it open and watch progress.

Task Board

Click on any task to view more details.

Task Detail View

Inside the task view you can see:

Task description Task description

Agent comments Agent comments

Proof of work proof of work

Model used model used

Token usage and cost cost

8. Spec Details

Open the Specs page at http://localhost:9200/specs

Find the spec for the board you want to review and click its card.

Spec Card

The spec details page shows:

MetricDescription
Tasks generatedAll tasks created from the spec
Execution timelineWhen each task ran
Models usedWhich agents handled which tasks
Time takenPer-task and total duration
Cost breakdownBuild cost, review cost, and total

Spec Details Cost

9. View Generated Output

Once all tasks show DONE, check the generated project files:

cd /path/to/pomodoro
ls

You should see files generated by the tasks (e.g., index.html). Open the app in your browser:

Option A — VS Code Live Server

  1. Install the Live Server extension in VS Code
  2. Open the project folder in VS Code
  3. Right-click index.html → "Open with Live Server"

Open with Live Server

Your browser will open the app at http://127.0.0.1:5500.

Option B — Python (works on any OS, no extensions needed)

python -m http.server 8080

Then open http://localhost:8080 in your browser.

output

10. Troubleshooting

claude code not found error

Odin requires at least one AI agent to be available.

If Claude Code is not installed but Codex is available, change the base agent in your project configuration.

Edit .odin/config.yaml in your project directory:

base_agent: codex

If neither is installed, install Claude Code first: claude.ai/code

odin command not found

Make sure the Odin CLI is installed:

cd /path/to/harness-kit/odin
pipx install -e .

Restart your terminal if the command is still not found.

Tasks stuck in TODO / Celery not starting

First, check that dev.sh is still running:

# Terminal where you ran ./dev.sh — is it still active?
# You should see periodic log lines like "Task completed" or "Worker ready"

If the terminal closed or Celery crashed, restart it:

./dev.sh

If tasks are still stuck after restarting:

  1. Stop dev.sh (press Ctrl+C)
  2. Remove stale Celery state: 
    rm -rf .celery/
  3. Restart dev.sh: 
    ./dev.sh

Port already in use

If port 8000 or 5173 is already occupied, dev.sh will fail. Find and stop the conflicting process:

# Find the process using the port (macOS / Linux)
lsof -i :8000

# Stop it
kill -9 <PID>

Repeat for port 5173 if needed.

./dev.sh permission denied

Make the script executable:

chmod +x dev.sh
./dev.sh