# 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_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 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_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).