typebasedio/ctask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

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

Browse Source 
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>
This commit is contained in:
warren
2026-04-06 17:44:25 -04:00
parent 44e3c38248
commit 401092f55a
4 changed files with 645 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+88
View File
@@ -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).
docs/commands.md
+295
View File
@@ -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 <query> [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 <query> [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 <query> [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 <query>
```
**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 <query> [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 `<query>` 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 |
docs/install.md
+104
View File
@@ -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/<you>/AppData/Local/ctask/bin/ctask-statusline.sh"
}
}
```
Replace `<you>` 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`
docs/troubleshooting.md
+158
View File
@@ -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\<you>\AppData\Local\ctask\bin\`
### Workspace / task folders
```
%USERPROFILE%\ai-workspaces\
<category>\
<YYYY-MM-DD>_<slug>\
task.yaml
CLAUDE.md
notes.md
context\
output\
logs\
sessions.log
```
Default: `C:\Users\<you>\ai-workspaces\`
Override with the `CTASK_ROOT` environment variable.
### Session logs
Each workspace has its own session log at:
```
<workspace>\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 <query>` to see the workspace contents list.
### Claude Code settings
```
%USERPROFILE%\.claude\settings.json
```
This is where the `statusLine` configuration lives.