Codekanban CLI

CodeKanban CLI

Use this skill after installing the codekanban-cli package and copying this packaged skill into the user's Codex skills directory.

When to use this skill

• Use it for CodeKanban project, web-session, workflow, session, and terminal operations.
• Prefer web-session for structured interactive AI work.
• Use workflow start only when the user explicitly wants a PTY-style startup flow.
• Use terminal continue only when the user explicitly wants to continue an existing terminal session.

Command boundary

The CLI surface is limited to the scopes documented here: project, web-session, workflow, session, terminal, file, and auth. The former Kanban task scope is removed; do not invent task or board API calls. For repository work, send instructions through web-session or use the file commands.

Prerequisites

• codekanban-cli is installed and available on PATH
• The CodeKanban service is reachable
• Default service URL is http://127.0.0.1:3007
• If auth is enabled, save a token once with codekanban-cli auth save-token

First-time initialization

If the service is open and does not require auth, you can start immediately:

codekanban-cli project list

If the service requires auth, save a token once:

printf '%s' '<PASSWORD>' | codekanban-cli auth save-token --password-stdin

You can also save a token directly:

codekanban-cli auth save-token --token-file <TOKEN_FILE>

Saved session data lives in a user-level config directory, not in a repository:

• Windows: %APPDATA%\codekanban-cli\session.json
• macOS/Linux: $XDG_CONFIG_HOME/codekanban-cli/session.json or ~/.config/codekanban-cli/session.json

Project targeting rules

Target selection priority:

1. --project-id
2. --project-name
3. local current directory fallback for local servers only
4. explicit --path

Use these project helpers first when the user refers to a project by name:

codekanban-cli project list
codekanban-cli project resolve --project-name codekanban

Then operate on the resolved project:

codekanban-cli web-session create --project-name codekanban --agent codex --workflow-mode plan --permission-level elevated --title "Planning session"
codekanban-cli session list --project-name codekanban

If the user says something like "create a web session for project codekanban and pull git updates", follow this pattern:

1. Resolve the project by name
2. Create the web session for that project
3. Send the requested instruction into the new session
4. Watch or poll the session if the user expects completion status

For the common structured flow "create a session, answer user-input questions, execute the plan, and wait for done", prefer the built-in orchestration command:

codekanban-cli web-session run --project-name codekanban --agent codex --text "Create a concise plan first, then implement it." --strict-cwd

Image inputs

Use repeatable --image <path> options when the initial task or a follow-up message needs local image references:

codekanban-cli web-session run --project-name codekanban --agent codex --text "Match the implementation to these references." --image ./desktop.png --image ./mobile.png --strict-cwd
codekanban-cli web-session send --session-id <SESSION_ID> --text "Also account for this state." --image ./reference.png

• --image is supported by web-session run and web-session send.
• Image paths are local to the machine running codekanban-cli, even when the CodeKanban service is remote.
• The option is repeatable and can be combined with existing --attachment-id values.
• Web-session attachments currently support images only and are subject to the server attachment size limit.
• Use web-session attach --file <path> followed by --attachment-id <id> only when an uploaded image must be reused across commands.

Remote web-session test loop (minimal SDK)

Use this when you want a short programmable remote verification loop without stitching websocket events by hand.

• Prefer SDK polling helpers over websocket event streams for this flow.
• runWebSessionUntilDone(...) already handles:
  • ordinary structured user-input prompts
  • latest-plan execution
  • terminal-state debounce through settleMs
• It still stops and returns control on approvals or timeouts.
• Keep this template focused on session orchestration; do file verification separately if you need it.

node --input-type=module <<'EOF'
import { CodeKanbanClient } from '@codekanban/sdk';

const baseURL = 'http://10.128.128.111:6112';
const projectPath = '/home/dev/test1';
const initialTask = 'Use the current directory as the project root. Keep the task short, ask structured questions only if needed, and do not do unrelated work.';

const client = new CodeKanbanClient({ baseURL });

const health = await fetch(`${baseURL}/api/v1/health`);
if (!health.ok) {
  throw new Error(`health check failed: ${health.status}`);
}

const { project } = await client.resolveProject({
  path: projectPath,
  ensureProject: true,
});

const session = await client.createWebSession({
  projectId: project.id,
  agent: 'codex',
  workflowMode: 'plan',
  permissionLevel: 'elevated',
  reasoningEffort: 'low',
  title: 'remote test loop',
});

await client.sendWebSessionMessage({
  sessionId: session.id,
  text: initialTask,
});

const result = await client.runWebSessionUntilDone({
  projectId: project.id,
  sessionId: session.id,
  intervalMs: 1500,
  timeoutMs: 120000,
  settleMs: 2000,
});

console.log(JSON.stringify({
  projectId: project.id,
  sessionId: session.id,
  stopReason: result.stopReason,
  finalPhase: result.finalState?.phase ?? null,
  lastAssistant: result.finalState?.lastAssistantMessage?.text ?? null,
}, null, 2));
EOF

Remote server rules

When the service is remote, do not assume the local Codex machine path matches the server path.

• Prefer --project-name or --project-id
• Use --path only when you know the path is valid on the machine running CodeKanban
• If project-name matching is ambiguous, use project resolve --project-name <name> first; if it lists multiple candidates, retry with --project-index <n>

Read references/project-targeting.md when you need a decision guide for local vs remote targeting or ambiguous project names.