Getting Started

Set up a Tick project in under 5 minutes. All you need is a filesystem — no server, no database, no API keys.

Installation

Install the Tick CLI globally:

npm install -g tick-md

# Or with npx (no install)
npx tick-md init

Initialize a Project

Run tick init inside any directory or git repository. This creates the Tick scaffolding alongside your existing files:

$ cd my-project
$ tick init

✓ Created .tick/config.yml
✓ Created .tick/schema.json
✓ Created TICK.md
✓ Created tasks/
✓ Tick project initialized

Project Structure

After initialization, your project looks like this:

project-root/
├── .tick/
│   ├── config.yml          # Project config, agent registry, workflow rules
│   ├── schema.json         # JSON Schema for task validation
│   └── hooks/              # Optional pre/post commit hooks
├── TICK.md                 # Master task index (single source of truth)
├── tasks/                  # Optional detail files for complex tasks
│   ├── TASK-001.md
│   ├── TASK-002.md
│   └── ...
└── .tick.lock              # Lock file for concurrent access

Single File vs. Multi-File

Tick uses a hybrid approach: one master index file (TICK.md) contains all task metadata and short descriptions, while optional detail files in tasks/ hold extended specifications, acceptance criteria, and discussion threads.

This optimizes for the most common operation: an agent reading the full project state. A single file read gives complete context. Detail files are only accessed when an agent claims a task and needs the full spec.

Create Your First Task

$ tick add "Build user auth flow" --priority high --tags engineering,backend

✓ Created TASK-001: Build user auth flow
  Priority: high
  Tags: engineering, backend
  Status: backlog

This appends a new task block to your TICK.md:

### TASK-001 · Build user auth flow

```yaml
id: TASK-001
status: backlog
priority: high
assigned_to: null
claimed_by: null
created_by: @gianni
created_at: 2026-02-07T10:00:00-05:00
tags: [engineering, backend]
depends_on: []
blocks: []
history:
  - ts: 2026-02-07T10:00:00  who: @gianni  action: created
```

> Build user auth flow

Claim and Work

An agent (human or bot) claims a task before starting work:

$ tick claim TASK-001

✓ Claimed TASK-001: Build user auth flow
  Status: backlog → in_progress
  Claimed by: @gianni

The claim command acquires the file lock, sets claimed_by, transitions status to in_progress, appends a history entry, and commits.

Update Progress

Add notes as you work:

$ tick comment TASK-001 "Set up JWT middleware, working on refresh tokens next"

✓ Comment added to TASK-001

Complete the Task

$ tick done TASK-001

✓ Completed TASK-001: Build user auth flow
  Status: in_progress → review
  Released claim

By default, tick done moves the task to review. To skip review and go straight to done:

$ tick done TASK-001 --skip-review

Check Project Status

$ tick status

┌─────────────────────────────────────┐
│  adgena-v2 · Adgena V2 Launch      │
├─────────┬───────────────────────────┤
│ backlog │ 12 tasks                  │
│ todo    │  8 tasks                  │
│ active  │  3 tasks (2 bots, 1 you) │
│ review  │  5 tasks                  │
│ done    │ 15 tasks                  │
└─────────┴───────────────────────────┘

Active agents:
  @claude-code  working  TASK-023  (2m ago)
  @content-bot  working  TASK-031  (45s ago)
  @gianni       online   TASK-001  (just now)

Example: Multi-Agent Workflow

Here’s a complete workflow showing how Tick coordinates a human, a coding bot, and a QA bot on the same project:

Step 1 — Human creates and assigns tasks

$ tick add "Build landing page" --priority high --tags frontend --assign @claude-code
$ tick add "Write launch email" --priority medium --tags content --assign @content-bot
$ tick add "E2E tests for landing" --priority medium --tags qa --depends-on TASK-001

Step 2 — Coding bot picks up work

# @claude-code reads TICK.md, sees assigned task
$ tick claim TASK-001
# ... builds the landing page ...
$ tick comment TASK-001 "Built responsive landing with hero, features, pricing sections"
$ tick done TASK-001

Step 3 — QA bot auto-triggers

# @qa-bot watches for dependency completion
# TASK-003 depends on TASK-001 which is now done
$ tick claim TASK-003
# ... runs E2E tests ...
$ tick comment TASK-003 "All 12 tests passing. Screenshots attached in detail file."
$ tick done TASK-003 --skip-review

Step 4 — Human reviews

$ tick query --status review

TASK-001 · Build landing page (review) assigned:@gianni
TASK-002 · Write launch email (review) assigned:@gianni

$ tick status TASK-001 done   # Approve
$ tick status TASK-002 in_progress --comment "Needs punchier CTA"  # Reject back

Configuration

The .tick/config.yml file controls all project-level behavior. Here’s a complete example:

# .tick/config.yml

project:
  name: adgena-v2
  title: Adgena V2 Launch
  description: AI-powered video generation platform

workflow:
  states: [backlog, todo, in_progress, review, done]
  initial: backlog
  terminal: [done]
  transitions:
    backlog: [todo]
    todo: [in_progress, backlog]
    in_progress: [review, blocked]
    review: [done, in_progress]
    blocked: [todo, in_progress]
    done: [reopened]

roles:
  engineer:
    can_claim_tags: [engineering, frontend, backend, devops, api]
    can_transition: [todo->in_progress, in_progress->review]
  copywriter:
    can_claim_tags: [content, copy, marketing, email]
    can_transition: [todo->in_progress, in_progress->review]
  tester:
    can_claim_tags: [qa, testing]
    can_transition: [review->done, review->in_progress]
  owner:
    can_claim_tags: ["*"]
    can_transition: ["*->*"]

locking:
  timeout_seconds: 30
  retry_attempts: 3
  retry_delay_ms: 500

git:
  auto_commit: true
  auto_push: false
  commit_prefix: "[tick]"
  push_on_sync: false

notifications:
  webhook_url: null
  events: [claimed, completed, blocked, overdue]

Git Configuration

By default, auto_commit is enabled, meaning every mutation command (add, claim,done, comment, etc.) automatically creates a git commit with the prefix [tick]. This provides an automatic audit trail of all task changes.

You can override this behavior per-command using flags:

• --commit — Force auto-commit for this command, even if disabled in config
• --no-commit — Skip auto-commit for this command, even if enabled in config

# Skip auto-commit for a specific task creation
$ tick add "Draft task" --no-commit

# Force commit even if auto_commit is disabled in config
$ tick done TASK-001 --commit

Next Steps

• Read the Protocol Spec for the full data format and coordination rules
• See the CLI Reference for all available commands
• Check out the GitHub repo for source code and examples