96 lines
3.6 KiB
Markdown
96 lines
3.6 KiB
Markdown
# 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.6.0 -- local use, not published to any package registry. Windows-primary, cross-platform design.
|
|
|
|
## Key Features
|
|
|
|
- **Named workspaces** with consistent layout (task metadata, agent instructions, notes, context, output, logs)
|
|
- **Session traceability** -- automatic file-change snapshot logging on every session
|
|
- **Agent-agnostic** -- built-in profiles for Claude Code and OpenCode, plus a `custom` escape hatch for any CLI agent or shell
|
|
- **Global config** -- optional user-level config file for defaults (agent, roots, session mode), with source attribution in `doctor`
|
|
- **Session recovery** -- PID-aware lease detection: a workspace whose owner process has died is recovered immediately, with no stale-wait
|
|
- **Query resolution** -- find workspaces by name, slug, or substring
|
|
- **Status line** -- persistent session context inside Claude Code's UI
|
|
- **Doctor** -- verify setup, diagnose configuration problems, and validate agent setup
|
|
- **Safe delete** -- active workspace protection prevents accidental data loss
|
|
|
|
## Install (Windows)
|
|
|
|
```powershell
|
|
cd C:\Users\Warren\claude_tasks\ctask
|
|
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 last` | Resume the most recently updated workspace |
|
|
| `ctask open <query>` | Open a workspace directory without launching the agent |
|
|
| `ctask attach <workspace>` | Attach to a workspace via tmux (persistent session) |
|
|
| `ctask info <query>` | Display workspace metadata and path |
|
|
| `ctask path <query>` | Print the absolute filesystem path of a workspace |
|
|
| `ctask notes <query>` | Print a workspace's notes.md to stdout |
|
|
| `ctask archive <query>` | Mark a workspace as archived |
|
|
| `ctask restore <query>` | Un-archive a workspace (set status back to active) |
|
|
| `ctask agents check [workspace]` | Validate the agent configuration for a workspace |
|
|
| `ctask doctor` | Verify ctask setup and diagnose configuration problems |
|
|
| `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
|
|
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).
|