docs: add README, install, commands, and troubleshooting documentation
README.md: project overview, quick start, command table, install/uninstall summary. docs/install.md: prerequisites, install/uninstall procedures, install location, PATH behavior, status-line setup. docs/commands.md: all 9 commands with syntax, flags, examples, query resolution, env vars, exit codes. docs/troubleshooting.md: practical fixes for PATH, status line, doctor failures, delete protection, file locations. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,295 @@
|
||||
# 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:**
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
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:**
|
||||
|
||||
```powershell
|
||||
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:**
|
||||
|
||||
```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.
|
||||
|
||||
**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 |
|
||||
|
||||
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 |
|
||||
Reference in New Issue
Block a user