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:
bashocto-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.
bashocto-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:
bashocto-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.
bashocto-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:
bashbody_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:
bashprintf '{"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"
Metadata
Metadata is persistent task state, not a log. Read it on entry and write only
high-value facts that will be read again (for example pr_url,
pipeline_status, blocked_reason). Inspect the contract first — the set path
is keyed by a metadata id:
bashocto-cli schema task.metadata.set octo-cli loop task metadata list <task-id> --workspace-id <ws>
Status and assignment side effects
Status and assignment are done through task update, not a dedicated command:
bashocto-cli loop task update <task-id> --workspace-id <ws> --status <status> octo-cli loop task update <task-id> --workspace-id <ws> \ --assignee-id <uuid> --assignee-type expert # or expert_team, member
Changing status is not cosmetic — it can start or stop work. In the standard
Fleet workflow backlog parks an assigned task, in_progress means work is in
progress, and in_review means the work is awaiting review. Use done only
after the work is accepted or no review is required; done and cancelled are
terminal. Moving out of backlog to an active status can trigger the assigned
expert to run. Confirm the exact status values accepted by your workspace via
the schema.
Dispatch and executions
To create a task and dispatch it to an expert or expert-team in one call, use
quick-create with a prompt and an assignee id:
bashocto-cli loop task quick-create --workspace-id <ws> \ --prompt "Investigate the login redirect bug" --expert-id <uuid> # or --expert-team-id <uuid>
Each dispatch produces an execution. Read run state and stop a runaway run rather than guessing:
bashocto-cli loop task execution list <task-id> --workspace-id <ws> octo-cli loop task execution cancel <task-id> <execution-id> --workspace-id <ws> octo-cli loop task rerun <task-id> --workspace-id <ws> --execution-id <execution-id>
Cancelling and rerunning are writes with side effects — confirm before running them unless the user asked.
Mention side effects
Comment bodies can contain mention links that Fleet interprets as actions, not decoration. Mentioning an expert or expert-team triggers a run; mentioning a person is a notification only. Look up real ids before composing a mention:
bashocto-cli loop expert list --workspace-id <ws> octo-cli loop expert-team list --workspace-id <ws> octo-cli loop workspace member list <ws> --workspace-id <ws>
Do not mention an expert or expert-team just to say thanks, confirm, or wrap up — re-mentioning the responder can trigger a fresh run and create a loop. Confirm the exact mention link syntax against the product before relying on it.
External agent boundary
An external agent does not automatically inherit Loop context. When asked to act on a task or comment, obtain or derive: the task id, the triggering comment id and its parent (if replying), the target workspace, whether writes are allowed, and whether mentions / status changes / reruns / dispatch are allowed. If any of these is missing and the operation would write state, ask first. For read-only investigation, gather context with JSON output and state what is still missing.
