From 401092f55ac93f5e39c1f00de3b39ae110c82e0e Mon Sep 17 00:00:00 2001 From: warren Date: Mon, 6 Apr 2026 17:44:25 -0400 Subject: [PATCH] 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) --- README.md | 88 ++++++++++++ docs/commands.md | 295 ++++++++++++++++++++++++++++++++++++++++ docs/install.md | 104 ++++++++++++++ docs/troubleshooting.md | 158 +++++++++++++++++++++ 4 files changed, 645 insertions(+) create mode 100644 README.md create mode 100644 docs/commands.md create mode 100644 docs/install.md create mode 100644 docs/troubleshooting.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4d94cc2 --- /dev/null +++ b/README.md @@ -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 ` | Reopen a workspace and launch the agent | +| `ctask open ` | Open a workspace in a shell (no agent) | +| `ctask info ` | Display workspace metadata | +| `ctask archive ` | Mark a workspace as archived | +| `ctask last` | Resume the most recently updated workspace | +| `ctask doctor` | Verify ctask setup | +| `ctask delete ` | 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). diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..049171f --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,295 @@ +# Commands + +## ctask new + +Create a new task workspace and launch the agent. + +``` +ctask new [title] [flags] +``` + +If title is omitted, generates `task-HHMMSS`. + +**Flags:** + +| Flag | Short | Default | Description | +|------|-------|---------|-------------| +| `--category` | `-c` | `general` | Workspace category subdirectory | +| `--shell` | | off | Open interactive shell instead of agent | +| `--agent` | `-a` | `claude` | Command to exec as the agent | +| `--no-launch` | | off | Create workspace only, do not launch | +| `--container` | | off | Deferred to a future release | + +**Examples:** + +```powershell +ctask new "fix auth bug" +ctask new -c scripts "backup helper" +ctask new --no-launch "json cleanup" +ctask new --shell "test env" +ctask new --agent aider "refactor api" +ctask new +``` + +When `--no-launch` is used, no session is started and no session log is written. + +--- + +## ctask list + +Show recent workspaces in reverse-chronological order. + +``` +ctask list [flags] +``` + +**Flags:** + +| Flag | Short | Default | Description | +|------|-------|---------|-------------| +| `--all` | `-a` | off | Include archived workspaces | +| `--category` | `-c` | all | Filter by category | +| `--limit` | `-n` | 20 | Maximum entries to show | + +**Examples:** + +```powershell +ctask list +ctask list --all +ctask list -c scripts -n 5 +``` + +Output columns: status, mode, category, date, slug. + +--- + +## ctask resume + +Reopen an existing workspace and launch the agent. + +``` +ctask resume [flags] +``` + +Resolves the workspace by query (exact directory name, exact slug, or case-insensitive substring). Archived workspaces are excluded by default. + +**Flags:** + +| Flag | Short | Default | Description | +|------|-------|---------|-------------| +| `--shell` | | off | Open shell instead of agent | +| `--agent` | `-a` | from task.yaml | Override agent command | +| `--container` | | off | Deferred to a future release | + +**Examples:** + +```powershell +ctask resume auth-bug +ctask resume backup +ctask resume --shell auth-bug +ctask resume --agent aider auth-bug +``` + +If multiple workspaces match, prints all matches and exits. If none match, prints an error. + +Session logging runs automatically: file changes during the session are recorded in `logs/sessions.log`. + +--- + +## ctask open + +Open a workspace directory in an interactive shell without launching the agent. + +``` +ctask open [flags] +``` + +Spawns a new subshell in the workspace directory. Does not modify the caller's shell session. + +**Flags:** + +| Flag | Short | Default | Description | +|------|-------|---------|-------------| +| `--all` | `-a` | off | Include archived workspaces in query resolution | + +**Examples:** + +```powershell +ctask open auth-bug +``` + +--- + +## ctask info + +Display metadata and path for a workspace without entering it. + +``` +ctask info [flags] +``` + +**Flags:** + +| Flag | Short | Default | Description | +|------|-------|---------|-------------| +| `--all` | `-a` | off | Include archived workspaces in query resolution | + +**Examples:** + +```powershell +ctask info auth-bug +ctask info backup +``` + +Shows: slug, title, category, status, mode, agent, created/updated timestamps, path, and directory contents. + +--- + +## ctask archive + +Mark a workspace as archived. The workspace stays in place but is hidden from default listings and query resolution. + +``` +ctask archive +``` + +**Examples:** + +```powershell +ctask archive auth-bug +``` + +To see archived workspaces, use `ctask list --all`. To resolve archived workspaces in other commands, use the `--all` flag where available. + +--- + +## ctask last + +Resume the most recently updated workspace. Equivalent to `ctask resume` on whichever workspace has the latest `updated_at` timestamp. + +``` +ctask last [flags] +``` + +**Flags:** + +| Flag | Short | Default | Description | +|------|-------|---------|-------------| +| `--shell` | | off | Open shell instead of agent | +| `--agent` | `-a` | from task.yaml | Override agent command | + +**Examples:** + +```powershell +ctask last +ctask last --shell +``` + +If no active workspaces exist, prints an error and exits. + +--- + +## ctask doctor + +Verify that ctask is correctly set up. Read-only -- never modifies anything. + +``` +ctask doctor +``` + +Checks: +1. Workspace root exists and is writable +2. Default agent command is found on PATH +3. Status-line helper script exists at the expected location +4. Claude Code `statusLine` is configured in `~/.claude/settings.json` +5. At least one workspace exists + +Exits 0 if all checks pass, 1 if any fail. Each failure includes a concrete fix instruction. + +**Example output:** + +``` + [PASS] Workspace root exists: C:\Users\Warren\ai-workspaces + [PASS] Default agent found: claude + [PASS] Status line helper found: C:\Users\Warren\AppData\Local\ctask\bin\ctask-statusline.sh + [PASS] Claude Code status line configured + [PASS] Workspaces found: 5 tasks (2 archived) + +5 checks passed, 0 failed +``` + +--- + +## ctask delete + +Permanently remove a workspace directory. + +``` +ctask delete [flags] +``` + +**Flags:** + +| Flag | Short | Default | Description | +|------|-------|---------|-------------| +| `--force` | `-f` | off | Skip confirmation prompt | +| `--all` | `-a` | off | Include archived workspaces in query resolution | + +**Examples:** + +```powershell +ctask delete old-task +ctask delete --force old-task +ctask delete --all --force archived-task +``` + +**Safety:** +- Confirmation is required by default. `--force` skips it. +- If the workspace has an active session (running in another terminal), deletion is refused even with `--force`. Exit the session first. +- If the workspace is the most recently updated one, a note is printed before confirmation. + +--- + +## Query Resolution + +Commands that take a `` argument (`resume`, `open`, `info`, `archive`, `delete`) resolve workspaces in this order: + +1. Exact directory name match (e.g. `2026-04-06_auth-bug`) +2. Exact slug match (e.g. `auth-bug`) +3. Case-insensitive substring match (e.g. `auth`) + +If multiple workspaces match, all matches are printed and the command exits. If none match, an error is printed. + +Archived workspaces are excluded from matching by default. Use `--all` where supported to include them. + +--- + +## Environment Variables + +ctask exports these into every child session: + +| Variable | Description | +|----------|-------------| +| `CTASK_TASK` | Task slug | +| `CTASK_MODE` | Execution mode (`local`) | +| `CTASK_ROOT` | Resolved workspace root path | +| `CTASK_WORKSPACE` | Full workspace path | +| `CTASK_CATEGORY` | Category name | + +Configure ctask behavior with: + +| Variable | Default | Description | +|----------|---------|-------------| +| `CTASK_ROOT` | `%USERPROFILE%\ai-workspaces` | Workspace root directory | +| `CTASK_AGENT` | `claude` | Default agent command | + +--- + +## Exit Codes + +| Code | Meaning | +|------|---------| +| 0 | Success | +| 1 | General error (multiple matches, not found, invalid args, doctor failure) | +| 2 | Missing required argument | +| 127 | Agent command not found | diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..3bf9fe9 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,104 @@ +# Install and Uninstall + +## Prerequisites + +- **Go 1.26+** -- install with `winget install GoLang.Go` +- **just** (optional task runner) -- install with `winget install Casey.Just` + +## Local Install (Windows) + +Build from the local repo and install to `%LOCALAPPDATA%\ctask\bin`: + +```powershell +cd C:\Users\Warren\claude_tasks\ctask_v0.1 +powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1 +``` + +Or with just: + +```powershell +just install +``` + +### What gets installed + +| File | Location | +|------|----------| +| ctask.exe | `%LOCALAPPDATA%\ctask\bin\ctask.exe` | +| ctask-statusline.sh | `%LOCALAPPDATA%\ctask\bin\ctask-statusline.sh` | +| ctask-statusline.ps1 | `%LOCALAPPDATA%\ctask\bin\ctask-statusline.ps1` | + +The install script: +- Builds `ctask.exe` from the local repo +- Copies the binary and status-line helpers to the install directory +- Adds `%LOCALAPPDATA%\ctask\bin` to the user PATH if not already present +- Creates a `.ctask-path-added` marker to track PATH ownership + +**Open a new terminal** after install for PATH changes to take effect. + +### Verify + +```powershell +ctask --version +ctask doctor +``` + +## Dev Build (no install) + +```powershell +cd C:\Users\Warren\claude_tasks\ctask_v0.1 +go build -o ctask.exe . +``` + +Or: `just build` + +This produces a local `ctask.exe` in the repo directory without installing it. + +## Status Line Setup + +After install, configure Claude Code to show ctask session context. Add to `~/.claude/settings.json`: + +```json +{ + "statusLine": { + "type": "command", + "command": "bash /c/Users//AppData/Local/ctask/bin/ctask-statusline.sh" + } +} +``` + +Replace `` with your Windows username. Run `ctask doctor` to get the exact path for your system. + +## Uninstall + +```powershell +cd C:\Users\Warren\claude_tasks\ctask_v0.1 +powershell -NoProfile -ExecutionPolicy Bypass -File scripts/uninstall.ps1 +``` + +Or: `just uninstall` + +### What uninstall removes + +- `ctask.exe`, `ctask-statusline.sh`, `ctask-statusline.ps1` from the install directory +- The PATH entry, **only if** the install script originally added it (tracked by `.ctask-path-added` marker) +- The empty install directory after files are removed + +### What uninstall does NOT remove + +- Your workspace data (`%USERPROFILE%\ai-workspaces` or wherever `CTASK_ROOT` points) +- Task folders, notes, session logs, or any workspace contents +- The Claude Code `statusLine` configuration in `~/.claude/settings.json` +- PATH entries that were added manually (not by the install script) + +## Remote / Public Install + +Not available. This project is not published to any package registry, GitHub release, or remote Go module. Build and install locally from the repo. + +## Running Tests + +```powershell +go test ./... -v -count=1 +``` + +Or: `just test` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..13a6325 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,158 @@ +# Troubleshooting + +## "ctask" is not recognized + +The install directory is not on your PATH, or you need to open a new terminal. + +**Fix:** + +1. Open a new terminal (PATH changes require a new session) +2. Run `ctask --version` +3. If still not found, verify the install location exists: + +```powershell +Test-Path $env:LOCALAPPDATA\ctask\bin\ctask.exe +``` + +4. If the file exists but the command isn't found, check PATH: + +```powershell +$env:Path -split ';' | Select-String 'ctask' +``` + +5. If not in PATH, re-run the install script: + +```powershell +powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1 +``` + +## Status line not appearing in Claude Code + +The status line shows ctask session context at the bottom of Claude Code's UI. If it's not showing: + +**1. Check that the helper script exists:** + +```powershell +ctask doctor +``` + +Look for the "Status line helper found" check. + +**2. Check Claude Code configuration:** + +`ctask doctor` also checks whether `~/.claude/settings.json` has a `statusLine` entry. If it reports a failure, it gives the exact JSON to add. + +**3. Verify the config uses the right path format:** + +Claude Code runs statusLine commands through bash. The path must use forward slashes: + +```json +"command": "bash /c/Users/Warren/AppData/Local/ctask/bin/ctask-statusline.sh" +``` + +Not backslashes -- those get stripped by bash. + +**4. Restart Claude Code** after changing settings.json. + +## ctask doctor failures + +### "Workspace root not found" + +The default workspace root (`%USERPROFILE%\ai-workspaces`) doesn't exist yet. + +**Fix:** Create it, or create your first workspace: + +```powershell +ctask new "my first task" +``` + +### "Agent command not found" + +The configured agent (`claude` by default) isn't installed or isn't on PATH. + +**Fix:** Install the agent, or set a different one: + +```powershell +$env:CTASK_AGENT = "aider" +ctask doctor +``` + +### "Status line helper not found" + +The status-line helper scripts aren't at the expected location. + +**Fix:** Re-run the install script: + +```powershell +powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1 +``` + +### "Claude Code status line not configured" + +The `~/.claude/settings.json` file is missing the `statusLine` key or it's misconfigured. + +**Fix:** `ctask doctor` prints the exact JSON to add. Copy it into your settings file. + +### "No workspaces found" + +You haven't created any workspaces yet. + +**Fix:** `ctask new "my first task"` + +## "Cannot delete the active workspace" + +You tried to delete a workspace that has a running session (in this terminal or another). + +**Fix:** Exit the session first (close the agent or type `exit` in the shell), then retry the delete. + +This protection works by checking for a `.ctask/manifest-start.json` file inside the workspace, which only exists during a live session. It also checks the `CTASK_WORKSPACE` environment variable for same-session attempts. + +## Where are my files? + +### Installed ctask files + +``` +%LOCALAPPDATA%\ctask\bin\ + ctask.exe + ctask-statusline.sh + ctask-statusline.ps1 +``` + +Default: `C:\Users\\AppData\Local\ctask\bin\` + +### Workspace / task folders + +``` +%USERPROFILE%\ai-workspaces\ + \ + _\ + task.yaml + CLAUDE.md + notes.md + context\ + output\ + logs\ + sessions.log +``` + +Default: `C:\Users\\ai-workspaces\` + +Override with the `CTASK_ROOT` environment variable. + +### Session logs + +Each workspace has its own session log at: + +``` +\logs\sessions.log +``` + +This is an append-only text file recording each session's start/end time, duration, and file changes. View it directly or use `ctask info ` to see the workspace contents list. + +### Claude Code settings + +``` +%USERPROFILE%\.claude\settings.json +``` + +This is where the `statusLine` configuration lives.