Axis Tasks

Git-based task management with time tracking for AI-powered dev workflows.

Markdown files. Shell scripts. Zero dependencies beyond bash and python3.

Built for developers who work with AI coding agents (Claude Code, Cursor, Windsurf) and want task + time tracking that lives in their repo, not in a separate app.

Why Axis Tasks?

• Your AI agent is the interface — no manual CLI commands. Send a document, meeting notes, or a Slack message to your agent, and it extracts tasks automatically.
• Time tracking from AI sessions — integrates with SpecStory to measure actual active work time, excluding AFK gaps. No manual start/stop needed.
• Git-native — tasks are markdown files with YAML frontmatter. Version controlled, diffable, searchable. Works with any git workflow.
• Billable/internal split — built-in client and project tracking with per-client reports and CSV export for invoicing.
• n8n automations — webhook endpoints to create tasks from ClickUp, Linear, meeting transcripts, or any tool that sends HTTP.
• Works with Axis CRM — optional integration validates clients against your CRM. Works standalone without it.

Install

npx axis-tasks init

This creates a tasks/ directory with everything you need.

cd tasks
./scripts/setup.sh    # verify environment

Requirements

Requirement	Version
bash	3.2+ (macOS default works)
python3	3.8+
git	any

Optional

Integration	What it does
SpecStory	Precise AFK-aware time tracking from AI session logs
Axis CRM	Client/project validation
Obsidian + Dataview	Live dashboards (today, weekly, billable)
n8n	Webhook automations (meeting > tasks, external tools > tasks)

How It Works

1. Create tasks

Your AI agent creates tasks from whatever you send it — documents, meeting notes, chat messages:

./scripts/new-task.sh "Fix checkout timeout" \
  --client acme \
  --priority high \
  --due 2026-04-18 \
  --tags "bugfix,backend" \
  --force

Or via n8n webhook from external tools:

curl -X POST https://your-n8n.example.com/webhook/axis-tasks-create \
  -H "Content-Type: application/json" \
  -d '{"title": "Fix checkout timeout", "client": "acme", "priority": "high"}'

2. Track time

Session flow (recommended):

./scripts/start-timer.sh fix-checkout       # start working
# ... work ...
./scripts/end-session.sh --desc "Fixed race condition in payment callback"
# → auto-calculates time (SpecStory or wall clock)
# → logs entry to daily timesheet + task file
# → stops timer

With SpecStory (optional, recommended): Install the SpecStory VS Code/Cursor extension. It logs AI conversations with timestamps. end-session.sh uses these to calculate actual active time — AFK gaps (5+ min) are excluded automatically.

Without SpecStory: Everything works — timer counts elapsed time from start to stop.

Manual:

./scripts/log-time.sh 2.5 --client acme --task fix-checkout --desc "debugging"

3. Complete and report

./scripts/complete-task.sh fix-checkout     # archive to done/
./scripts/report.sh --today                  # daily summary
./scripts/report.sh --csv --month > apr.csv  # CSV export for invoicing

Scripts

Script	Description
setup.sh	Verify environment, initialize directories
new-task.sh	Create a task (all fields via flags)
list-tasks.sh	List active tasks with filters
start-timer.sh	Start timer on a task
end-session.sh	End session — auto-calculate time, log entry, stop timer
stop-timer.sh	Stop timer (low-level, use end-session.sh instead)
complete-task.sh	Complete, cancel, or block a task
log-time.sh	Manually log hours
report.sh	Generate reports (text or CSV)
specstory-time.sh	Analyze SpecStory sessions

All scripts are non-interactive — designed to be called by AI agents. No read prompts, everything via flags.

Flags reference

new-task.sh

./scripts/new-task.sh "Title" [flags]

  --client slug       Client identifier
  --project slug      Project identifier
  --priority value    low | medium | high | urgent (default: medium)
  --due YYYY-MM-DD    Deadline
  --estimated hours   Estimated hours
  --tags "a,b,c"      Comma-separated tags
  --force             Skip CRM validation

list-tasks.sh

./scripts/list-tasks.sh [flags]

  --client slug       Filter by client
  --status value      Filter by status (todo, in-progress, blocked)
  --due               Only tasks with deadlines, sorted by due date

end-session.sh

./scripts/end-session.sh --desc "description" [flags]

  --desc "text"       Required. What was done.
  --hours 2.5         Override calculated hours
  --task slug         Task slug (auto-detected from timer)
  --client slug       Client (auto-detected from timer or task)
  --project slug      Project (auto-detected from timer or task)

stop-timer.sh

./scripts/stop-timer.sh --desc "description" [flags]

  --desc "text"       Required. What was done.
  --hours 2.5         Override calculated hours

complete-task.sh

./scripts/complete-task.sh [flags] task-slug

  --cancel            Cancel instead of complete
  --block             Mark as blocked (stays in active/)
  --force             Complete even with 0 hours logged

log-time.sh

./scripts/log-time.sh hours --desc "text" [flags]

  --client slug       Client
  --project slug      Project
  --task slug         Link to task file
  --start HH:MM       Start time (default: now)
  --stop HH:MM        End time (default: calculated)
  --date YYYY-MM-DD   Date (default: today)

report.sh

./scripts/report.sh [flags]

  --today             Today only
  --week              This week (default)
  --month             This month
  --client slug       Filter by client
  --from YYYY-MM-DD   Custom range start
  --to YYYY-MM-DD     Custom range end
  --csv               CSV output (pipe to file)

Directory Structure

tasks/
├── active/           # Current tasks (todo, in-progress, blocked)
├── done/             # Archived tasks (done, cancelled)
├── time/             # Daily time entries (YYYY-MM-DD.md)
├── scripts/          # Shell scripts (10)
├── templates/        # Task and time entry templates
├── rules/            # Field definitions, lifecycle, time tracking rules
├── dashboards/       # Obsidian Dataview dashboards
├── automations/      # n8n workflow JSON exports
└── CLAUDE.md         # AI agent instructions

Task File Format

Each task is a markdown file with YAML frontmatter:

---
title: "Fix checkout timeout"
created: 2026-04-14
status: in-progress
priority: high
client: "acme"
project: "e-shop"
billable: true
tags: [bugfix, backend]
due: 2026-04-18
estimated_hours: 4
total_hours: 1.5
completed:
---

## Description

Checkout times out after 30s on slow connections.

## Checklist

- [x] Identify root cause
- [ ] Fix payment callback race condition
- [ ] Add timeout configuration

## Time log

| Date | Start | Stop | Hours | Description |
|---|---|---|---|---|
| 2026-04-14 | 09:00 | 10:30 | 1.5 | Debugging + root cause analysis |

## Notes

Found race condition in payment gateway callback handler.

Axis CRM Integration

Axis Tasks works standalone. When used alongside Axis CRM:

• new-task.sh validates client slugs against CRM's clients/ directory
• report.sh --client filters match CRM client structure
• Meeting > Tasks automation can reference CRM meeting paths

To connect, place your CRM directory as a sibling (../crm/) or set AXIS_CRM_DIR environment variable.

Automations (n8n)

Two webhook workflows included in automations/:

Meeting > Tasks

Receives meeting action items, creates one task file per item on GitHub.

Webhook > Task (generic)

Creates a single task from any external tool (ClickUp, Linear, Zapier, etc.).

See automations/README.md for setup, input schemas, and customization guide.

Dashboards (Obsidian)

Three Dataview-powered dashboards:

Dashboard	Shows
dashboards/today.md	In-progress, todo, blocked, completed today
dashboards/week-summary.md	Weekly hours, active tasks, completed
dashboards/billable.md	Billable hours per client/month

Requires Obsidian with the Dataview plugin.

For AI Agents

Open CLAUDE.md in your workspace. It contains complete instructions for Claude Code, Cursor, and other AI coding agents — how to create tasks, track time, and generate reports.

The scripts are designed to be called programmatically:

• Non-interactive (no prompts, all input via flags)
• Deterministic exit codes (0 = success, non-zero = error)
• Partial slug matching for task lookup
• JSON output available (specstory-time.sh --json)

License

MIT