ctask/docs/commands.md

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:

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

List workspaces in reverse-chronological order.

ctask list [flags]

By default, ctask list shows all active workspaces -- both tasks and projects. Use --task or --projects to narrow by type, and --all to include archived workspaces.

Flags:

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

--task and --projects are mutually exclusive; passing both returns a usage error.

Examples:

ctask list                       # active tasks AND projects
ctask list --all                 # everything (incl. archived)
ctask list --task                # active tasks only
ctask list --task --all          # all tasks (incl. archived)
ctask list --projects            # active projects only
ctask list --projects --all      # all projects (incl. archived)
ctask list -c scripts -n 5

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

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:

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, considering both tasks and projects. Equivalent to ctask resume on whichever active workspace has the latest updated_at timestamp. Archived workspaces are excluded.

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.

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:

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