Skip to content

Latest commit

 

History

History
205 lines (143 loc) · 7.22 KB

QUICKSTART.md

File metadata and controls

205 lines (143 loc) · 7.22 KB

KFC Quickstart

Use this page as the shortest path to run Kami Flow Codex (KFC) correctly.

Run in KFC Repo

This is the maintainer and dogfooding repository (kamiflow-codex-starter).

npm install
npm run bootstrap

If you need to test KFC inside this repo fixtures:

npm run dogfood:link
npm run dogfood:smoke

If you need client linking, prepare the package from this repo once:

npm run link:self

Run in Client Project

Do not use npm run ... from this repo in client projects.

From the root of the external client repository (new/existing folder, not kamiflow-codex-starter):

kfc client --force

kfc client --force now runs one smart-recovery cycle by default, installs the project-local runtime skill at .agents/skills/kamiflow-core/SKILL.md, creates .kfc/CODEX_READY.md, scaffolds private client lessons at .kfc/LESSONS.md plus .local/kfc-lessons/, ensures .gitignore contains .kfc/, .local/, and .agents/, and auto-launches:

codex exec --full-auto "Read .kfc/CODEX_READY.md and execute the mission."

It still prints:

  • Onboarding Status: PASS|BLOCK
  • Stage: init|bootstrap|ready_brief|plan_ready|execution_ready|blocked|done
  • Error Code: CLIENT_*
  • Recovery: <exact command> when blocked
  • Next: <single concrete next action>

To keep bootstrap setup-only and skip the automatic handoff:

kfc client --force --no-launch-codex

Low-level equivalent (only when you need manual bootstrap control):

kfc client bootstrap --project . --profile client --force

If auto-launch is disabled or fails, run the exact fallback command printed by KFC. Codex should then read .kfc/CODEX_READY.md, read .kfc/LESSONS.md when present, and continue autonomously.

This flow is designed for no user reminder loop after bootstrap. Codex should continue from the generated brief and the project-local skill without waiting for routine chat reminders. The lesson scaffolding is private and gitignored by design; Codex can still read it locally.

To manage private project lessons after bootstrap:

kfc client lessons capture --project . --type incident --title "Broken setup" --lesson "Use X before Y" --context "Short trigger/context"
kfc client lessons pending --project .
kfc client lessons show --project . --id LESSON-20260307-001
kfc client lessons promote --project . --id LESSON-20260307-001 --summary "Durable lesson Codex should remember"
kfc client lessons list --project .

Use .local/kfc-lessons/ for raw private history and .kfc/LESSONS.md for the curated lessons Codex should read in future sessions.

After work is complete, cleanup is required:

kfc client done

During normal implementation turns, Codex should run check validations automatically and report Check: PASS|BLOCK before final response.

Update KFC In Client Project

If the client project already has KFC installed, use the client-side update flow:

kfc client update --project .

This is preview-only by default. It reports:

  • detected install source (link|git|file_or_tarball|unknown)
  • whether package.json will change
  • exact apply command

To execute the update:

kfc client update --project . --apply

Important behavior:

  • linked installs: refresh-only; no dependency rewrite
  • git installs: reinstall from saved spec or --from
  • file/tarball installs: require --from <folder|tgz> for apply
  • apply always reruns client refresh/verification without auto-launching Codex

Copy Codex Sessions Between Machines

# on each machine once: generate local age key + trust self
kfc session key gen --name <device-name>

# view your public key (share this with trusted devices)
kfc session key show

# add trusted destination device(s) on source machine
kfc session trust add --name <peer-device> --pubkey <age1...>

# source machine: push active session (auto-id: --id > CODEX_THREAD_ID > latest session file)
kfc session push --to E:/transfer/codex-sessions

# source machine: push exact session id
kfc session push --id 019caccc-f25d-7151-ad1d-6eab893d714d --to E:/transfer/codex-sessions

# destination machine: pull latest indexed session into ~/.codex/sessions
kfc session pull --from E:/transfer/codex-sessions

# destination machine: pull exact session id
kfc session pull --from E:/transfer/codex-sessions --id 019caccc-f25d-7151-ad1d-6eab893d714d

Transfer folder stores encrypted .kfc-session.json artifacts plus minimal metadata index (kfc-session-index.json) using age recipient encryption.

Mobile Remote Surface

Optional advanced usage:

kfc remote serve --project . --host 127.0.0.1 --port 4320

This starts a separate mobile-friendly web surface for:

  • viewing the mirrored session state
  • reading the transcript
  • sending serialized prompts into the workstation queue

Recommended network model: private reachability such as Tailscale. See resources/docs/REMOTE_RUNBOOK.md.

Bound Codex Session Chat

Optional advanced utility:

kfc-chat bind --project . --session-id 019caccc-f25d-7151-ad1d-6eab893d714d
kfc-chat serve --project .

This starts a separate browser surface for:

  • one bound Codex session per project
  • WebSocket live transcript and session state
  • guarded prompt submission via codex exec resume <SESSION_ID> <prompt>
  • manual codex resume <SESSION_ID> handoff for terminal-style continuation

Runbook: resources/docs/KFC_CHAT_RUNBOOK.md.

Troubleshooting

  • kfc: command not found: run npm link @kamishino/kamiflow-codex again in the client project.
  • Missing plan UI: rerun kfc client --force.
  • Missing project-local KFC skill: rerun kfc client --force.
  • Missing client lessons file: rerun kfc client --force.
  • Codex did not auto-launch: rerun the exact Manual fallback: command printed by KFC, or use kfc client --force --no-launch-codex if you want setup only.
  • kfc client update is blocked for file/tarball installs: rerun with --from <folder|tgz> --apply.
  • Plan bootstrap failed: run kfc flow ensure-plan --project . (or kfc plan init --project . --new as compatibility fallback).
  • Flow behavior mismatch: run kfc client doctor --project . --fix.
  • If onboarding reports Onboarding Status: BLOCK, follow the printed Recovery: command exactly.
  • Rules mismatch: rerun kfc client --force.
  • Cannot find local Codex sessions folder: run kfc session where.
  • kfc session push says no trusted recipients: run kfc session key gen --name <device> then kfc session trust add --name <peer> --pubkey <age1...>.
  • Pull decrypt failure: verify local key exists (kfc session key show) and source machine encrypted for your recipient.
  • kfc-chat says no Codex session is bound: run kfc-chat bind --project . --session-id <id> first.
  • In KFC repo after skill edits, if runtime instructions are stale: run npm run codex:sync:skills -- --force.

Next Docs

  • resources/docs/CLIENT_KICKOFF_PROMPT.md
  • resources/docs/CLIENT_A2Z_PLAYBOOK.md
  • resources/docs/COMMAND_BOUNDARY_POLICY.md
  • resources/docs/CODEX_KFC_PLAN_RUNBOOK.md
  • resources/docs/CODEX_RULES_RUNBOOK.md
  • resources/docs/PORTABILITY_RUNBOOK.md
  • resources/docs/REMOTE_RUNBOOK.md
  • resources/docs/KFC_CHAT_RUNBOOK.md