ctask/cli-spec-v0.1.md

ctask CLI Specification (v0.1)

Global Options

ctask [command] [options] [arguments]
ctask -h | --help
ctask --version

Commands

---

ctask new [title]

Create a new task workspace and launch the agent.

ctask new [title] [options]

Arguments:

• title — Human-readable task name (optional). If omitted, generates task-HHMMSS.

Options:

Flag	Short	Default	Description
--category	-c	general	Workspace category subdirectory
--container		off	Launch in container sandbox (v0.2 — prints notice in v0.1)
--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

Behavior:

• new always creates a fresh workspace. If a workspace with the same date+slug exists, append -2, -3, etc.
• Slugs are derived from the title: lowercase, non-alphanumeric replaced with hyphens, trimmed
• Workspace created at $CTASK_ROOT/<category>/<YYYY-MM-DD>_<slug>/
• Seed files written only if they do not already exist

Examples:

# Basic — creates workspace, launches claude
ctask new "arch notes"

# With category
ctask new -c scripts "backup helper"

# Container mode
ctask new --container -c risky "unknown installer"

# Shell instead of agent
ctask new --shell "test env"

# Create workspace but don't launch anything
ctask new --no-launch "json cleanup"

# Use aider instead of claude
ctask new --agent aider "refactor api"

# Auto-generated name
ctask new

Output:

[ctask] created general/2026-04-05_arch-notes
[ctask] local :: arch-notes
[ctask] ~/ai-workspaces/general/2026-04-05_arch-notes

---

ctask list

Show recent workspaces in reverse-chronological order.

ctask list [options]

Options:

Flag	Short	Default	Description
--all	-a	off	Include archived workspaces
--category	-c	all	Filter by category
--limit	-n	20	Maximum entries to show

Output format:

active  local      general   2026-04-05  arch-notes
active  container  risky     2026-04-04  unknown-installer
active  local      scripts   2026-04-03  backup-helper

Columns: status, mode, category, date, slug.

Examples:

# Recent workspaces
ctask list

# Only scripts category
ctask list -c scripts

# Include archived
ctask list --all

# Last 5
ctask list -n 5

---

ctask resume <query>

Reopen an existing workspace and launch the agent.

ctask resume <query> [options]

Arguments:

• query — Workspace slug, partial name, or full directory name (required)

Options:

Flag	Short	Default	Description
--container		off	Resume in container mode (v0.2 — prints notice in v0.1)
--shell		off	Open shell instead of agent
--agent	-a	from task.yaml	Override agent command

Resolution:

1. Exact directory name match under $CTASK_ROOT/*/* → use it
2. Exact slug match (portion after date prefix) → use it
3. Case-insensitive substring match against slug → use if unique
4. Multiple matches → print all matches and exit 1
5. No matches → error and exit 1

Archived workspaces are excluded from matching by default.

Behavior:

• Updates updated_at in task.yaml
• Sets environment variables
• Prints launch banner
• Execs agent or shell

Examples:

# Resume by slug
ctask resume arch-notes

# Resume by partial match
ctask resume backup

# Resume by full directory name
ctask resume 2026-04-05_arch-notes

# Resume in container mode (even if originally local)
ctask resume --container arch-notes

# Resume with shell
ctask resume --shell arch-notes

On multiple matches:

Multiple workspaces match "notes":
  general/2026-04-05_arch-notes
  research/2026-04-03_migration-notes
Specify a more precise query.

---

ctask open <query>

Open a workspace directory without launching the agent.

ctask open <query> [options]

Options:

Flag	Short	Default	Description
--all	-a	off	Include archived workspaces in query resolution

Behavior:

• Resolves workspace (same rules as resume)
• Updates updated_at
• Sets environment variables
• Spawns a new interactive subshell in the workspace directory with ctask prompt prefix
• Does NOT launch the agent
• Does NOT mutate the caller's existing shell session — this is a subshell, not a cd

This is equivalent to ctask resume --shell <query> but reads more naturally for "I just want to look at the files."

Examples:

# Open workspace in shell
ctask open arch-notes

---

ctask info <query>

Display metadata and path for a workspace without entering it.

ctask info <query> [options]

Options:

Flag	Short	Default	Description
--all	-a	off	Include archived workspaces in query resolution

Output:

Task:      arch-notes
Title:     arch notes
Category:  general
Status:    active
Mode:      local
Agent:     claude
Created:   2026-04-05 14:30:22
Updated:   2026-04-05 15:12:00
Path:      ~/ai-workspaces/general/2026-04-05_arch-notes

Contents:
  task.yaml
  CLAUDE.md
  notes.md
  context/
  output/
  logs/

Examples:

ctask info arch-notes
ctask info backup

---

ctask archive <query>

Mark a workspace as archived.

ctask archive <query>

Behavior:

• Resolves workspace (same rules as resume)
• Sets status: archived and archived_at timestamp in task.yaml
• Workspace stays in place (not moved or deleted)
• Archived workspaces are hidden from ctask list unless --all is passed

Examples:

ctask archive arch-notes
ctask archive 2026-04-03_backup-helper

Output:

[ctask] archived: general/2026-04-05_arch-notes

---

Environment Variables

Set by ctask (exported into every child session)

Variable	Example	Description
CTASK_TASK	arch-notes	Task slug
CTASK_MODE	local	Execution mode
CTASK_ROOT	/home/warren/ai-workspaces	Resolved workspace root (absolute path)
CTASK_WORKSPACE	/home/warren/ai-workspaces/general/2026-04-05_arch-notes	Full workspace path
CTASK_CATEGORY	general	Category

Read by ctask (user-configurable input)

Variable	Default	Description
CTASK_ROOT	~/ai-workspaces (Unix) or %USERPROFILE%\ai-workspaces (Windows)	Workspace root directory
CTASK_AGENT	claude	Default agent command

Implementation note on CTASK_ROOT: ctask reads the caller's CTASK_ROOT as config input (may contain ~ or relative path), resolves it to an absolute path, then exports the resolved value into the child process environment. The child session always sees a fully resolved absolute path.

---

Exit Codes

Code	Meaning
0	Success
1	General error (multiple matches, not found, invalid args)
2	Missing required argument
127	Agent command not found

---

Shell Prompt Behavior

In --shell mode

Ephemeral PS1 prefix, no permanent config changes:

(ctask:arch-notes|local) warren@host:~/ai-workspaces/general/2026-04-05_arch-notes$

In agent mode

Banner printed before exec:

[ctask] local :: arch-notes
[ctask] ~/ai-workspaces/general/2026-04-05_arch-notes

---

Container Mode (Deferred to v0.2)

The --container flag is accepted but prints a notice that container mode is not yet available in v0.1. This keeps the CLI interface stable so users and scripts don't need to change when container support lands.

[ctask] container mode is not available in v0.1. Use local mode or see docs for manual container setup.

Design intent for v0.2: persistent named container, Podman-first (Docker fallback), Claude Code only inside container. See MVP contract for details.

---

Status Line Integration

Claude Code status line

ctask ships a small helper script for Claude Code's status line feature. When ctask environment variables are set, it renders session context at the bottom of the Claude Code UI.

Setup (add to ~/.claude/settings.json):

{
  "statusLine": {
    "type": "command",
    "command": "bash /path/to/ctask-statusline.sh"
  }
}

On Windows, use the PowerShell variant:

{
  "statusLine": {
    "type": "command",
    "command": "powershell -NoProfile -File C:\\path\\to\\ctask-statusline.ps1"
  }
}

Output when in a ctask session:

(ctask:arch-notes|local) ~/ai-workspaces/general/2026-04-05_arch-notes

Output when NOT in a ctask session: empty (no output, falls through gracefully).

Fallback for non-Claude agents

The ephemeral shell prompt prefix (PS1 on Unix, PROMPT on Windows) in --shell mode provides session context for any tool that doesn't support a dedicated status line.