gioe/tusk

tusk

A portable task and context handoff system for AI-assisted software projects. Tusk gives Claude Code and Codex a local SQLite database, CLI, skills/prompts, and durable task records so agents can track, prioritize, resume, and complete work without relying on the original chat transcript.

What You Get

• tusk CLI — single entry point for task state, context hydration, criteria, dependencies, sessions, review, and merge operations
• Skills and prompts — Claude Code skills and Codex prompt ports for task workflows (/tusk-init, /tusk, /create-task, /groom-backlog)
• Durable context snapshots — objectives, tasks, criteria, progress, jots, reviews, and context atoms preserve enough handoff context for a future agent to act
• Scripts — Python utilities for task briefs, duplicate detection, dependency management, summaries, dashboard data, and migrations
• Config-driven schema — define your project's domains, task types, agents, and validation rules in JSON; validation triggers are generated automatically

Quick Start

# Clone the repo somewhere on your machine
git clone https://github.com/gioe/tusk.git

# From your project root (must be a git repo)
cd /path/to/your/project
/path/to/tusk/install.sh

This will:

1. Install tusk, skills, scripts, and default config
2. Create tusk/config.json with defaults
3. Initialize the database at tusk/tasks.db

Then start a new Claude Code session and run /tusk-init — it will scan your codebase, suggest domains and agents, write your config, and seed tasks from TODOs.

You can also configure manually by editing tusk/config.json and running tusk init --force.

Context Handoff Model

Tusk treats the database as a durable context snapshot, not just a backlog. Objectives capture larger intent, tasks stay scoped to shippable work, criteria define completion, verifications prove the work, and compact context atoms preserve decisions, risks, assumptions, and memory for the