typebasedio
8304545840
Bump notes.md to anchor on v0.5.4:
- Top stanza + "Where we are": v0.5.4 shipped on main at merge commit
10b7d5a, installed binary reports v0.5.4.
- Insert "What v0.5.4 delivered" with the 8-commit list and
validation results.
- Insert "From v0.5.4 (new -- don't unlearn)" load-bearing design
points covering SessionStatus's display-only contract, the
session.json/mode naming preserved from v0.5.3, the column-14
alignment in info, the SESSION column / list --names invariant,
and the errArchivedWorkspace sentinel scoping.
- Append v0.5.4 Don't re-do entries (display-only SessionStatus, no
PID liveness in the helper, --names contract, archived em-dash,
sentinel scoping, cmd-vs-session boundary, no hardcoded "ctask").
- Replace "Next: v0.6 (planning)" with "Next: v0.6 Phase 1" listing
config file + schema_version + workspace.mode + source attribution
in doctor/info -- explicitly noting Phase 2 (agent profiles,
AGENTS.md, PID liveness, lazy-cleanup adoption) is out of scope
until Phase 1 is implemented and reviewed.
- Update Tree state, How to resume, Files to read first.
- Resolve closed limitations: v0.5.2 duplicate Cobra Error line, the
v0.5.3 invocation-name asymmetry (audit codified the split as the
right line), info/list session-state visibility, docs/commands.md
staleness.
- Record spec deviations: v0.5.4 spec referred to .ctask/lease.json
and session_mode but the actual code uses session.json and mode.
Implementation correctly preserved the existing names per the
spec's "no new metadata fields" constraint. Future specs touching
this surface should use the actual names.
ctask
A local CLI that creates and manages named AI-agent task workspaces.
ctask gives developers dedicated directories with consistent structure, visible session identity, environment context injection, and automatic session logging -- so you can start, resume, and organize AI-assisted work more safely and predictably.
Status
v0.2.0 -- local use, not published to any package registry. Windows-primary, cross-platform design.
Key Features
- Named workspaces with consistent layout (task metadata, notes, context, output, logs)
- Session traceability -- automatic file-change snapshot logging on every session
- Agent-agnostic -- default agent is Claude Code, but any CLI agent or shell works
- Query resolution -- find workspaces by name, slug, or substring
- Status line -- persistent session context inside Claude Code's UI
- Doctor -- verify setup and diagnose configuration problems
- Safe delete -- active workspace protection prevents accidental data loss
Install (Windows)
cd C:\Users\Warren\claude_tasks\ctask_v0.1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1
Installs to %LOCALAPPDATA%\ctask\bin. Open a new terminal after install.
See docs/install.md for full details.
Quick Start
# Verify setup
ctask doctor
# Create a new task workspace and launch Claude Code
ctask new "fix auth bug"
# List recent workspaces
ctask list
# Resume where you left off
ctask last
# Or resume a specific workspace
ctask resume auth-bug
Commands
| Command | Description |
|---|---|
ctask new [title] |
Create a new workspace and launch the agent |
ctask list |
Show recent workspaces |
ctask resume <query> |
Reopen a workspace and launch the agent |
ctask open <query> |
Open a workspace in a shell (no agent) |
ctask info <query> |
Display workspace metadata |
ctask archive <query> |
Mark a workspace as archived |
ctask last |
Resume the most recently updated workspace |
ctask doctor |
Verify ctask setup |
ctask delete <query> |
Permanently remove a workspace |
See docs/commands.md for full usage.
Status Line
ctask includes a status-line helper for Claude Code that shows session context at the bottom of the UI:
(ctask:fix-auth-bug|local) C:\Users\Warren\ai-workspaces\general\2026-04-06_fix-auth-bug
Run ctask doctor to check if the status line is configured. See docs/install.md for setup.
Uninstall
cd C:\Users\Warren\claude_tasks\ctask_v0.1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/uninstall.ps1
Removes ctask files only. Your workspaces and task data are never touched.