Octo Loop

Octo Loop

Use the loop namespace for Fleet control-plane operations. Product names are task, expert, expert-team, and execution; do not use the legacy issue/agent/squad names.

Terminology (legacy → current): agent → expert, squad → expert-team, issue → task, assign a task to an expert/expert-team and trigger its run → dispatch.

When to use / not use

Use this skill when the request targets a specific Loop workspace or task: reading or writing tasks, comments, projects, or metadata; working with experts or expert-teams (dispatch, schedule, trigger a run); replying to a comment, creating or triaging a task, updating status, or reading progress.

Do not use it for chat unrelated to Loop, for pure local file work, or when "issue" clearly means GitHub/Jira rather than Loop.

Authentication

Set OCTO_BOT_TOKEN to a bearer credential Fleet accepts directly, such as bf_, uk_, or octo_loop_. The CLI does not infer a human, device, or execution principal from a token prefix. Fleet verifies the credential and constructs the principal.

Outside daemon task mode, if a command fails with an auth error, check octo-cli auth status and let the user run octo-cli auth login. In OCTO_CREDENTIAL_MODE=task, those profile diagnostics are unavailable: report the auth failure so the daemon can refresh or replace the injected credential. Do not fabricate credentials. Never leak or store tokens, config keys, or API base URLs, and do not bypass workspace permissions with direct HTTP calls.

All Loop commands use the same gateway as every other domain. The embedded paths include the Fleet module namespace, so requests resolve under $OCTO_API_BASE_URL/fleet/api/v1/*.

Workspace selector

Workspace-scoped Loop commands require the --workspace-id <id> flag (sent as the X-Workspace-ID header). There is no environment fallback for it — pass it explicitly. Discover available workspaces first:

octo-cli loop workspace list
octo-cli loop workspace member list <workspace-id> --workspace-id <workspace-id>

Discover and execute operations

Output is JSON by default (--format json); parse JSON rather than scraping tables.

octo-cli loop task list --workspace-id <ws>
octo-cli loop task get <task-id> --workspace-id <ws>
octo-cli loop expert list --workspace-id <ws>
octo-cli loop expert-team list --workspace-id <ws>
octo-cli loop execution message list <execution-id> --workspace-id <ws>

Inspect the current contract before constructing a write:

octo-cli schema task.create
octo-cli schema task.comment.create
octo-cli schema expert.create
octo-cli schema expert_team.create

Repository operations, daemon device enrollment, task claim/heartbeat, and local runtime paths are intentionally not part of this CLI surface.

Read workflow

Read before you write.

octo-cli loop task get <task-id> --workspace-id <ws>
octo-cli loop task comment list <task-id> --workspace-id <ws>
octo-cli loop task metadata list <task-id> --workspace-id <ws>
octo-cli loop task children-by-parent --workspace-id <ws>

Comment history is paginated with --page / --page-size.

Explore other namespaces (project, expert, expert-team, expert-template, execution, runtime, skill, skill-file, autopilot, attachment, label, top-level comment) with --help — their shapes vary.

Write workflow

Treat writes as actions with side effects: creating comments, creating tasks, changing status, assigning/dispatching, rerunning executions, mentioning an expert or expert-team, and autopilot changes. If the user has not clearly asked for a write, confirm before executing.

Comment and description bodies go through a file

There is no --content-file flag. Body text is a request-body field, so pass it via --data, which accepts @file (or @- for stdin). Do not build the body inline with --content "$(cat ...)": the shell rewrites backticks, $(), variables, quotes, and newlines before the CLI sees them.

Write the body to a private temp file, wrap it as valid JSON (use jq -Rs . to escape the text safely), and clean up:

body_dir="$(mktemp -d)"
trap 'rm -rf "$body_dir"' EXIT
# ...write the comment body to "$body_dir/reply.md", preserving real newlines...
printf '{"content": %s}' "$(jq -Rs . < "$body_dir/reply.md")" > "$body_dir/body.json"

octo-cli loop task comment create <task-id> --workspace-id <ws> --data "@$body_dir/body.json"

Use mktemp -d, never a fixed path like ./reply.md (it can clobber a user file). To reply within a thread, add --parent-comment-id <comment-id>; individual flags override same-named fields in --data.

Task descriptions follow the same pattern — --description is a plain string flag with the same shell hazards, so prefer a JSON body from a file:

printf '{"title": %s, "description": %s}' \
  "$(jq -Rs . <<< 'Fix login redirect')" \
  "$(jq -Rs . < "$body_dir/description.md")" > "$body_dir/task.json"
octo-cli loop task create --workspace-id <ws> --data "@$body_dir/task.json"