# Commands

## ctask new

Create a new task or project workspace and launch the agent.

```
ctask new [title] [flags]
```

If title is omitted, generates `task-HHMMSS`.

**Flags:**

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--category` | `-c` | `general` (task) / `projects` (project) | Workspace category subdirectory |
| `--project` | | off | Create a long-lived project workspace (uses `CTASK_PROJECT_ROOT` if set, runs `git init`, project CLAUDE.md) |
| `--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
ctask new --project "billing service"
ctask new --project -c backend "billing service"
```

When `--no-launch` is used, no session is started and no session log is written.

### Project mode (`--project`)

`--project` is a thin variation on the normal task workflow for longer-lived work. It changes:

- `task.yaml` records `type: project`
- Default category becomes `projects`
- Workspace root falls back to `CTASK_PROJECT_ROOT` if set; otherwise `CTASK_ROOT`
- Built-in CLAUDE.md is the project-oriented template (overridable via seed directories)
- Seed order: built-in defaults -> general seed (`CTASK_SEED_DIR`) -> project seed (`CTASK_SEED_PROJECT_DIR`)
- `git init` runs if `git` is on PATH; a minimal `.gitignore` (`.ctask/` + `logs/sessions.log`) is created **only if no `.gitignore` was already provided by a seed**
- If `git` is not available, ctask prints `[ctask] git not found; skipped repository initialization` and continues

**Project root semantics:**

- `CTASK_PROJECT_ROOT` not set: workspace goes under `$CTASK_ROOT/projects/<date>_<slug>` (default category `projects` is appended)
- `CTASK_PROJECT_ROOT` set, no `-c`: workspace goes directly under `$CTASK_PROJECT_ROOT/<date>_<slug>` (no `projects/` subdirectory is appended)
- `CTASK_PROJECT_ROOT` set, explicit `-c <category>`: workspace goes under `$CTASK_PROJECT_ROOT/<category>/<date>_<slug>`

### Seed directories

On `ctask new`, after writing the built-in defaults, ctask copies the contents of an optional user seed directory into the workspace. Files in the seed directory overwrite the built-in defaults; subdirectories are preserved recursively. `task.yaml` and `.ctask/` at the seed root are always skipped.

| Variable | Default (Unix) | Default (Windows) |
|----------|---------------|-------------------|
| `CTASK_SEED_DIR` | `~/.config/ctask/seed/` | `%APPDATA%\ctask\seed\` |
| `CTASK_SEED_PROJECT_DIR` | `~/.config/ctask/seed-project/` | `%APPDATA%\ctask\seed-project\` |

The general seed is applied to every workspace. The project seed is applied **only** when `--project` is set, on top of the general seed (project seed wins). Both directories are optional; missing directories are silently ignored.

---

## ctask list

Show recent workspaces in reverse-chronological order.

```
ctask list [flags]
```

**Flags:**

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--all` | `-a` | off | Include archived workspaces |
| `--projects` | | off | Show project workspaces instead of task workspaces |
| `--category` | `-c` | all | Filter by category |
| `--limit` | `-n` | 20 | Maximum entries to show |

**Examples:**

```powershell
ctask list
ctask list --all
ctask list --projects
ctask list --projects --all
ctask list -c scripts -n 5
```

Output columns: status, mode, category, date, slug.

The `--all` flag controls archived visibility only. The `--projects` flag controls type filtering only. They combine independently:

- `ctask list` -- active tasks only
- `ctask list --all` -- active + archived tasks
- `ctask list --projects` -- active projects only
- `ctask list --projects --all` -- active + archived projects

Workspaces created before v0.3 (which have no `type` field in `task.yaml`) are treated as tasks.

---

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

v0.3 also reports the resolved general and project seed directory paths as informational `[INFO]` lines. These do not contribute to the pass/fail count -- absent seed directories are normal and supported.

**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 |
| `CTASK_TYPE` | `task` or `project` |

Configure ctask behavior with:

| Variable | Default | Description |
|----------|---------|-------------|
| `CTASK_ROOT` | `%USERPROFILE%\ai-workspaces` (Windows) / `~/ai-workspaces` (Unix) | Workspace root directory |
| `CTASK_AGENT` | `claude` | Default agent command |
| `CTASK_PROJECT_ROOT` | (none) | Workspace root for projects. When set, project workspaces are created directly under this path (no doubled `projects/` segment unless `-c` is passed). |
| `CTASK_SEED_DIR` | `%APPDATA%\ctask\seed\` (Windows) / `~/.config/ctask/seed/` (Unix) | General user seed directory copied into every new workspace. |
| `CTASK_SEED_PROJECT_DIR` | `%APPDATA%\ctask\seed-project\` (Windows) / `~/.config/ctask/seed-project/` (Unix) | Project seed directory copied only for `--project` workspaces (overlay on top of the general seed). |

---

## 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 |