The .octo File Format
The .octo file is a DSL for orchestration intent. It expresses what you want coordinated — which arms, what kind of surface, what tone to close with — not how to coordinate it. Arms and surfaces look different every run. The .octo file stays the same.
The same philosophy as .reach: you write the intent. Claude compiles the implementation.
Basic Structure
# morning.octo
name morning-brief
arms
- outlook.inbox since yesterday analyze urgent
- teams.planner status overdue
- teams.transcript latest summarize
- git.commits since yesterday analyze cadence
surface
title "Good morning. Here's what needs you."
show urgent-items
actions
draft-reply → reach outlook.draft from selected
send-summary → reach outlook.draft to team summarize all
snooze → reach teams.planner snooze selected
show-all → expand full output
close
tone warm
joke trueEight lines of intent. Claude compiles each arm to typed C#, runs them, reads the combined signal, generates the surface, captures input, acts, closes with personality.
Arms Block
Each arm is a REACH — declared with source, qualifier, and intent:
arms
- source qualifier intent
- outlook.inbox since yesterday analyze urgent
- teams.planner status overdue
- git.commits since yesterdayArm types:
| Type | Behavior |
|---|---|
| Read arm | Reaches into a source, returns findings. No side effects, runs freely. |
| Act arm | Changes state after human approval. Always gated by surface confirmation. |
| Signal arm | Writes a signal for another arm or process. |
Arms run in parallel where possible. Results held in OCTO context until the surface is generated. Arms don't know what the other arms found — OCTO holds the combined signal.
Surface Block
The surface is generated from findings, not pre-built. Claude reads what the arms found and authors the right surface for this moment.
surface.brief
Compact. Three items max. Fast acknowledgement. Morning brief, deployment check, quick status.
surface
type brief
title auto
items 3
actions approve | snooze | expandsurface.review
Detailed. Full findings visible. Multiple action paths. Sprint review, incident response, timesheet approval.
surface
type review
title auto
show all-findings
actions
approve → act arm
edit → return to draft
delegate → reach outlook.draft forward
archive → reach file.write to archivesurface.draft
Email or message preview before sending. Full content visible. Edit inline. Send or save.
surface
type draft
show email-preview
actions send | edit | save-draft | discardsurface.acknowledge
Simplest gate. Information delivered. One action to continue.
surface
type acknowledge
show summary
actions ok | snooze | escalateThe Close Block
Every OCTO session ends with a close. Not a system message. Not a log entry. A human moment — warm, brief, occasionally funny.
close
tone warm # warm | neutral | minimal
joke true # true | false
summary true # recap what was doneClaude authors the close based on what actually happened. The tone instruction shapes it. The joke flag adds levity. Neither is mandatory — tone minimal produces a clean exit.
Example closes:
# After morning brief with reply sent:
"Sarah will appreciate that.
One less thing before your first meeting."
# After sprint review — all red:
"Ten weeks at redline. The data doesn't lie.
Take the valley week. You've earned it."
# After timesheet posted:
"Logged. [TIMESHEET] has been fed.
It was hungry."
# After deployment verified — all green:
"Green across the board.
Rare. Enjoy it."The close is not optional. Personality is what separates a tool from something you want to use again tomorrow.
Workflow Examples
deploy.octo
name deploy-verify
arms
- browser.page "https://staging.internal/health" extract status
- db.query env staging sql "SELECT COUNT(*) FROM DeployLog WHERE Date = TODAY()"
- git.commits since yesterday analyze summary
- teams.transcript latest summarize deployment-mentions
surface
type brief
title "Deployment status — {date}"
actions
all-clear → reach outlook.draft to team subject "Deploy verified ✓"
flag-issue → reach outlook.draft to lead subject "Deploy issue flagged"
investigate → expand full findings
close
tone neutral
joke falsereview.octo
name sprint-cadence-review
arms
- outlook.inbox since 10-weeks-ago analyze cadence where subject contains project
- outlook.calendar since 10-weeks-ago analyze density
- git.commits since 10-weeks-ago analyze after-hours benchmark 15%
surface
type review
title "Sprint health — 10 week read"
show rpm-verdict after-hours-benchmark cadence-by-month
actions
share-findings → reach outlook.draft to manager summarize
save-report → reach file.write sprint-review-{date}.reach-artifact
plan-recovery → prompt.input "When does your valley week start?"
close
tone warm
joke true
summary truetimesheet.octo
name daily-timesheet
arms
- git.commits since today analyze summary map-to-requests
- outlook.calendar since today analyze meetings
- outlook.inbox since today analyze threads
surface
type review
title "Today's timesheet — review before posting"
show drafted-entries
actions
post → reach timesystem.timesheet post entries
edit → return to entries
save → reach file.write timesheet-{date}-draft.json
close
tone warm
joke false
summary trueDesign Principles
Arms are independent — each arm reaches without knowing what the others found. OCTO holds the combined signal. Arms don't talk to each other.
The surface is always generated — never pre-built, never a fixed form. Claude reads the findings and authors the right surface for this moment.
Read arms run freely. Act arms need approval. — Same principle as REACH. The surface is the gate. Nothing changes state without human confirmation.
The close has personality — every session ends with a human moment. A tool you use once. Something with personality you use daily.
.octo files are the sharing unit — share a .octo file. Someone runs it against their data. The arms adapt. Same pattern, different context.