ctask/docs/commands.md

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:

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:

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:

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:

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:

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:

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:

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:

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