docs: add README, install, commands, and troubleshooting documentation

README.md: project overview, quick start, command table, install/uninstall summary. docs/install.md: prerequisites, install/uninstall procedures, install location, PATH behavior, status-line setup. docs/commands.md: all 9 commands with syntax, flags, examples, query resolution, env vars, exit codes. docs/troubleshooting.md: practical fixes for PATH, status line, doctor failures, delete protection, file locations. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06 17:44:25 -04:00
parent 44e3c38248
commit 401092f55a
4 changed files with 645 additions and 0 deletions
@@ -0,0 +1,88 @@
+# 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)
+
+```powershell
+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](docs/install.md) for full details.
+
+## Quick Start
+
+```powershell
+# 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](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](docs/install.md) for setup.
+
+## Uninstall
+
+```powershell
+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.
+
+## Troubleshooting
+
+See [docs/troubleshooting.md](docs/troubleshooting.md).