cli-copilot-worker

cli-copilot-worker is a copilot-only worker cli built on @github/copilot-sdk.

it runs markdown task files, keeps a local daemon for async jobs, lets you keep talking to the same conversation over time, and can fail over across multiple copilot profile dirs when one profile gets weird.

what you need

• node 22+
• github copilot cli installed
• a working copilot oauth login

login first

do this once if copilot is not already ready:

copilot login
copilot -p "reply with exactly ok."

if the second command prints ok, the cli has a real auth session to use.

the fastest real run

this is the quickest end-to-end check:

cat >/tmp/math-task.md <<'EOF'
calculate 12 * 13.
write only the final number and a newline to /tmp/math-result.txt.
do not write anything else.
EOF

npm exec --yes --package=cli-copilot-worker -- cli-copilot-worker run /tmp/math-task.md --cwd "$PWD"
cat /tmp/math-result.txt

you should see:

156

why npm exec instead of plain npx here? because it is the most predictable cross-shell path in this environment for the published cli. it is the one we actually verified.

the command set

cli-copilot-worker run <task.md>
cli-copilot-worker send <conversation-id> <message.md>
cli-copilot-worker answer <conversation-id> <answer.md>
cli-copilot-worker read <conversation-id>
cli-copilot-worker list
cli-copilot-worker info <conversation-id>
cli-copilot-worker job list
cli-copilot-worker job status <job-id>
cli-copilot-worker job wait <job-id>
cli-copilot-worker job read <job-id>
cli-copilot-worker job cancel <job-id>
cli-copilot-worker daemon start
cli-copilot-worker daemon status
cli-copilot-worker daemon stop
cli-copilot-worker doctor

a normal workflow

1. run a task

npm exec --yes --package=cli-copilot-worker -- \
  cli-copilot-worker run /tmp/math-task.md --cwd "$PWD"

2. inspect what happened

npm exec --yes --package=cli-copilot-worker -- \
  cli-copilot-worker list

npm exec --yes --package=cli-copilot-worker -- \
  cli-copilot-worker info <conversation-id>

npm exec --yes --package=cli-copilot-worker -- \
  cli-copilot-worker read <conversation-id> --follow

3. send a follow-up

cat >/tmp/followup.md <<'EOF'
now append the word done to /tmp/math-result.txt on a new line.
EOF

npm exec --yes --package=cli-copilot-worker -- \
  cli-copilot-worker send <conversation-id> /tmp/followup.md

4. answer a copilot question

if the conversation hits waiting_answer, write the answer in markdown and submit it:

cat >/tmp/answer.md <<'EOF'
yes, use the existing file.
EOF

npm exec --yes --package=cli-copilot-worker -- \
  cli-copilot-worker answer <conversation-id> /tmp/answer.md

async mode

if you want the daemon to keep running the job in the background:

npm exec --yes --package=cli-copilot-worker -- \
  cli-copilot-worker run /tmp/math-task.md --cwd "$PWD" --async

then wait on the job:

npm exec --yes --package=cli-copilot-worker -- \
  cli-copilot-worker job wait <job-id>

output modes

text is the default.

if you want machine-friendly output:

npm exec --yes --package=cli-copilot-worker -- \
  cli-copilot-worker --output json info <conversation-id>

what the cli expects

• all task inputs are markdown files
• all follow-up messages are markdown files
• all answers are markdown files
• the daemon auto-starts when needed
• state lives under ~/.cli-copilot-worker

the supported entrypoint is the cli itself. the package is built to bootstrap through package-local tsx, so you do not need to install tsx globally.

model rules that matter

run --model <id> is validated live against the current copilot account and eligible profiles.

the runtime:

• keeps only the newest visible model in each family as canonical
• accepts older aliases like claude-sonnet-4.5 and maps them forward
• hard-blocks gpt-4.1
• hard-blocks claude-opus-4.6-fast
• throws the exact whitelist if you request a model your account does not allow

on the account used to verify this repo, the canonical set was:

• claude-haiku-4.5
• claude-opus-4.6
• claude-sonnet-4.6
• gpt-5.3-codex
• gpt-5.4
• gpt-5.4-mini

example:

npm exec --yes --package=cli-copilot-worker -- \
  cli-copilot-worker run /tmp/math-task.md --cwd "$PWD" --model gpt-5.4

fleet + failover

turn on fleet mode for every request:

export COPILOT_ENABLE_FLEET=1

turn on multi-profile failover:

export COPILOT_CONFIG_DIRS="$HOME/.copilot:/absolute/path/to/second-profile"

the daemon will prefer healthy profiles, cool down rate-limited ones, and keep enough metadata around for doctor, info, and job status output to explain what happened.

deterministic failover testing uses:

export CLI_COPILOT_WORKER_PROFILE_FAULTS='{"profile-1":"rate_limit"}'

that env var is mainly for testing, not normal use.

doctor and daemon

check the local environment:

npm exec --yes --package=cli-copilot-worker -- cli-copilot-worker doctor

inspect daemon state:

npm exec --yes --package=cli-copilot-worker -- cli-copilot-worker daemon status

stop it if you want a clean restart:

npm exec --yes --package=cli-copilot-worker -- cli-copilot-worker daemon stop

local repo dev

if you are inside the source repo:

npm install
npm run build
npm test
node --import tsx src/cli.ts doctor
node --import tsx src/cli.ts run /tmp/math-task.md --cwd "$PWD"

short troubleshooting

if it feels off, start here:

copilot -p "reply with exactly ok."
npm exec --yes --package=cli-copilot-worker -- cli-copilot-worker doctor

usual suspects:

• copilot is installed but not logged in
• you picked a blocked or unavailable model
• the daemon has stale state and wants a quick daemon stop
• you expected plain npx cli-copilot-worker ... to behave like npm exec --package=... -- cli-copilot-worker ...