Callee

Markdown-defined agents and deterministic workflows

Callee lets a repository define Role, Script, Human, Sequential, Loop, and Router agents as versioned Markdown or YAML. Markdown is the base authoring and generation format; YAML represents the same complete schema object with spec.body inline. Every kind has the same node boundary: it receives input, may update one root-run state object, and returns one artifact or a structured orchestration outcome.

Callee remains CLI-only. It uses Norma Runtime for ACP provider processes and Go ADK-aligned escalation semantics. It has no server, durable thread store, or handle binding.

Documentation

See the Callee engineering documentation for detailed guides, architecture, reference, and contributor material. This README stays focused on installation and first use.

Agent skills

Callee installs two complementary skills in your coding host:

| Skill | What it does | Result | | --- | --- | --- | | Run Agent | Discovers project-defined agents, resolves the selected tree and required parameters, and runs a Role, Script, Human, Sequential, Loop, or Router agent through its controlling terminal. | The completed root artifact and a concise capability trace, followed by the emitted run-wide and per-Role execution metrics. | | Create Agent | Authors a reusable Role, Script, Human, Sequential, Loop, or Router in Markdown or YAML. For a Role, it uses an embedded PromptKit template when one fits, then validates the file and resolved tree. | A validated agent or deterministic workflow below .callee/. |

These skills are host integrations: they teach Codex, Claude Code, Grok Build, Copilot CLI, OpenCode, or Cursor how to create and run Callee agents. Runtime ACP providers are a separate layer selected by spec.provider.type; they supply the model session for each Role. Host setup does not install or authenticate an ACP provider, even when the host and provider share a name.

Set up your coding host

Run setup from the project root with the complete one-shot npx command for your host below. No global Callee installation is required; each cell is directly executable as written. Setup installs both skills and six editable starter agents.

| Host | Setup | Run Agent | Create Agent | | --- | --- | --- | --- | | Codex | npx --yes @baldaworks/callee@latest setup codex | $callee:run-agent | $callee:create-agent | | Claude Code | npx --yes @baldaworks/callee@latest setup claude | /callee:run-agent | /callee:create-agent | | Grok Build | npx --yes @baldaworks/callee@latest setup grok | /callee-run-agent | /callee-create-agent | | Copilot CLI | npx --yes @baldaworks/callee@latest setup copilot | /callee-run-agent | /callee-create-agent | | OpenCode | npx --yes @baldaworks/callee@latest setup opencode | callee-run-agent skill (/callee wrapper) | callee-create-agent skill (/callee-create-agent wrapper) | | Cursor | npx --yes @baldaworks/callee@latest setup cursor | callee-run-agent skill | callee-create-agent skill |

Codex, Claude Code, Grok Build, and Copilot CLI setup use the repository's plugin marketplace. OpenCode setup writes skills and convenience commands below .opencode/; Cursor setup writes skills below .cursor/skills/. Existing local files are preserved; use --force only when setup-managed assets should be replaced. Host CLIs and credentials remain external.

Use Callee from your host

In Codex, invoke the Callee plugin directly and describe the outcome. Callee routes the request to the appropriate installed skill, so the :run-agent or :create-agent suffix is optional:

$callee Run workflows/investigate to explain this project's architecture and main entry points.

Create a reusable Role while selecting its provider, model, and reasoning:

$callee Create a Go code-review Role named roles/go-reviewer using the codex provider, model gpt-5.6-sol, and high reasoning.

Or compose existing agents into a deterministic workflow:

$callee Create a Loop workflow named workflows/implementation-goalkeeper with roles/implementer as worker and roles/reviewer as validator. Run at most five iterations and finish only when the reviewer approves.

The explicit $callee:run-agent and $callee:create-agent selectors remain available when you want to choose a skill directly. For other hosts, use the invocation shown in the setup table. Run Agent inspects the catalog and selected tree before execution. After completion, it returns the root artifact and a concise capability trace, then reports the run-wide and per-Role metrics emitted by Callee. Repeated and nested Role visits remain separate, and fields that were not emitted remain omitted. See Execution metrics for field definitions, presence rules, and aggregation boundaries. Create Agent validates every file it writes and the fully resolved tree.

npm CLI installation and quick start

These npm paths require Node.js with npm, which provides npx. For repeated direct shell use, install the npm launcher globally:

npm install --global @baldaworks/callee@latest
callee --version

For one-shot shell use without installing Callee, run the complete npx command:

npx --yes @baldaworks/callee@latest --version

Every setup target creates the same starter IDs. After running one setup command from the host table, inspect the installed agents and the safe, read-only workflow directly. These quick-start examples use the one-shot form:

npx --yes @baldaworks/callee@latest agent list
npx --yes @baldaworks/callee@latest agent view workflows/investigate
npx --yes @baldaworks/callee@latest agent run workflows/investigate --message "Explain this project's architecture and main entry points"

Validate one agent file without loading its referenced children:

npx --yes @baldaworks/callee@latest agent validate .callee/roles/reviewer.md

Import a remote Callee catalog subtree into the current project root:

npx --yes @baldaworks/callee@latest agent import acme/platform-agents --prefix vendor

When you are ready to make changes, run GoalKeeper through the same entrypoint:

npx --yes @baldaworks/callee@latest agent run roles/reviewer --message "Review the current changes"
npx --yes @baldaworks/callee@latest agent run workflows/goalkeeper --message "Implement the requested feature"

Override Role protocol and ACP permissions independently for one run:

callee agent run workflows/investigate --message "Ask for the target" --interactive=true
callee agent run workflows/investigate --message "Return one artifact" --interactive=false --permissions=deny
callee --permissions=allow agent view workflows/investigate

--interactive=true forces every Role visit in the selected tree, including nested, aliased, and repeated Loop visits, through the existing REPL protocol. --interactive=false forces every Role visit through the existing one-shot protocol. If the flag is omitted, each Role keeps its authored spec.interactive (or legacy spec.repl) behavior. --permissions=ask|allow|deny separately overrides every Role's ACP policy for agent run and agent view. The flags are value-compatible except for --interactive=false with --permissions=ask, which fails before registry loading. Neither override rewrites resources or specs.

The remaining CLI examples use callee for readability and assume the global npm installation above.

Secondary alternative: install from Go source

If you prefer the Go toolchain, install the executable with the Go version declared in go.mod:

go install github.com/baldaworks/callee/cmd/callee@latest
callee --version

Ensure the Go installation directory (normally $GOBIN or $GOPATH/bin) is on PATH.

agent run derives one whole-run mode. Interactive mode opens the controlling TTY for initial input, missing parameters, Human responses, permission questions, and REPL turns. A Human-free tree whose effective Roles are one-shot and use allow or deny runs non-interactively without opening /dev/tty; it requires an explicit nonblank --message and every required parameter. Non-interactive violations fail before provider startup. Info lifecycle events for every node, provider-turn heartbeats, and ACP permission events use stderr, so determine success from the exit status rather than stderr emptiness.

agent run emits run-wide metrics on its final agent run finished event and per-Role metrics on each Role's agent finished event. The successful root artifact is written once to stdout only after provider cleanup and the final stderr metrics event. See Execution metrics for the complete field, presence, and aggregation contract.

While a provider turn remains in flight, Callee also emits agent turn heartbeat every 10 seconds with turn_duration=<elapsed>. This heartbeat is scoped to the active provider turn only: it does not include Role rendering, session prepare, REPL idle time between turns, or composite execution.

Manual host setup

The one-shot npx ... setup commands above are the recommended installation path. Use the following steps only when you need to manage the host integration yourself. The marketplace commands and file mappings install only the two Callee skills and any host command wrappers; they do not write the six starter agents.

Marketplace hosts

Codex:

codex plugin marketplace add baldaworks/callee
codex plugin add callee@callee

Claude Code:

claude plugin marketplace add baldaworks/callee
claude plugin install callee@callee --scope project

Grok Build:

grok plugin marketplace add baldaworks/callee
grok plugin install callee@callee --trust

Copilot CLI:

copilot plugin marketplace add baldaworks/callee
copilot plugin install callee@callee

File-based hosts

For a manual file-based installation, copy the repository assets into the matching project directories without replacing unrelated or customized files:

| Host | Source | Project destination | | --- | --- | --- | | OpenCode skills | internal/cli/assets/opencode/skills/ | .opencode/skills/ | | OpenCode commands | internal/cli/assets/opencode/commands/ | .opencode/commands/ | | Cursor skills | internal/cli/assets/cursor/skills/ | .cursor/skills/ |

The OpenCode command files provide /callee and /callee-create-agent wrappers around the callee-run-agent and callee-create-agent skills.

To install the editable starter Roles and workflows manually, copy the contents of internal/cli/assets/starter/ into .callee/, preserving the roles/ and workflows/ directories. Review existing files before replacing them. Starter Roles select only spec.provider.type; provider model, mode, and reasoning use the ACP backend defaults. Pass --agent-root <dir> to callee when these resources should be discovered from and written under a different root.

Agent format

Agents are discovered recursively below two roots:

• $XDG_CONFIG_HOME/callee, or $HOME/.config/callee when XDG_CONFIG_HOME is unset;
• the current project's .callee directory.

Pass callee --agent-root <dir> ... to use one custom discovery root instead. When set, Callee ignores both default roots and treats <dir> as the only agent catalog and the default write target for generated or installed Callee resources, including agent import.

callee agent import <repo> [--ref <git-ref>] [--path <remote-dir>] [--prefix <namespace>] [--force] clones a remote git repository into a temporary checkout, discovers resources recursively under --path (default .callee), and stages the resulting local tree before writing anything. When <repo> is in owner/repo form, Callee treats it as GitHub shorthand and expands it to https://github.com/owner/repo.git before cloning. --prefix rewrites imported IDs and imported internal child refs into a namespace. Existing destination files are preserved unless --force is supplied, and git must be available on PATH.

Lowercase .md, .yaml, and .yml regular files are supported; symlinked files are skipped. Recursive discovery and remote import skip Markdown files without YAML frontmatter and structurally valid Markdown, YAML, or YML documents whose apiVersion is absent or not callee.metalagman.dev/v1alpha1; README.md is a common example. Malformed frontmatter/YAML and documents that declare the current API version remain strict errors, as does direct callee agent validate of a selected file. Directories such as roles/ and workflows/ are optional ID namespaces; kind alone determines behavior. The final extension is removed from the ID, so .callee/roles/reviewer.md and .callee/roles/reviewer.yaml both have ID roles/reviewer and conflict if both exist. IDs must be unique across both roots and all formats. Project agents do not shadow user agents; any duplicate makes discovery fail.

All agents use the same Kubernetes-style apiVersion/kind/spec envelope.

Agent kinds

Role

---
apiVersion: callee.metalagman.dev/v1alpha1
kind: Role
spec:
  description: Reviews changes.
  provider:
    type: codex
  permissions:
    mode: ask
  params:
    focus: Review focus
---
You are a reviewer.

Task:
{{ .Input }}

Focus:
{{ .Params.focus }}

A Role body must contain exactly one unconditional bare {{ .Prompt }} or {{ .Input }} insertion. .Prompt is the immutable original root prompt; .Input is this node occurrence's rendered input.

ACP provider configuration

Provider configuration is nested below spec.provider; flat provider fields are not supported.

| type | Default ACP command | Runtime prerequisite | | --- | --- | --- | | codex | Current Callee executable with bridge codex | Installed and authenticated Codex CLI | | claude | npx -y @zed-industries/claude-code-acp@latest | Node.js with npx, npm registry access on the first uncached run, and credentials accepted by the Claude Code ACP adapter | | opencode | opencode acp | Installed and authenticated opencode CLI | | copilot | copilot --acp --stdio | Installed and authenticated copilot CLI | | grok | grok agent stdio | Installed grok CLI authenticated with grok login or XAI_API_KEY | | cursor | agent acp | Installed and authenticated Cursor CLI; see the Cursor ACP documentation | | generic_acp | None | An ACP executable named by nonblank cmd |

The Codex ACP bridge is built into Callee, so the default does not download or launch a separate npm bridge package. Other provider commands must be on PATH when the Role runs. Callee does not install or authenticate runtime providers. A host integration and a provider may use the same product name, but setup of one does not satisfy the runtime prerequisites of the other.

Run callee bridge codex --help to inspect the embedded bridge directly. It uses stdin/stdout for ACP and does not require a controlling TTY. Place the root --debug flag before bridge codex for Callee diagnostics; place the bridge's own --debug flag after bridge codex for bridge diagnostics.

All provider types accept the following fields:

• type (required): one of the seven values above.
• cmd: executable override. Use extraArgs for its arguments.
• model: backend-specific model identifier.
• reasoning: backend-specific reasoning value, such as high when the backend supports it.
• mode: backend-specific session mode.
• extraArgs: ordered arguments appended to the resolved command.
• timeout: positive Go duration applied separately to provider process startup, the session creation/prepare sequence, and each provider turn; the default is 15m.

For example:

  provider:
    type: generic_acp
    cmd: my-acp-agent
    model: provider-model
    reasoning: high
    mode: review
    extraArgs:
      - --stdio
    timeout: 20m

Empty model, reasoning, and mode fields defer to the backend. Support for nonempty values is backend-specific. Gemini is not a supported Callee provider type.

Each Role may set spec.permissions.mode to ask, allow, or deny; omission defaults to ask. ask presents the provider-supplied choices on the controlling TTY and pauses the active provider-turn budget while --repl-timeout bounds the operator wait. allow automatically prefers allow_once and then allow_always; deny similarly prefers reject_once and then reject_always. A missing compatible option fails the run. See ACP permission requests for the exact policy, session, timeout, and failure contract.

The root-persistent --permissions=ask|allow|deny flag overrides that policy for every direct, nested, aliased, and repeated Role visit. It also projects effective permissions in agent view while retaining authored values. It does not change Role REPL/one-shot protocol. Without explicit --interactive, the effective tree needs a TTY when it contains an interactive Role, ask, or a Human; otherwise it runs without one.

To temporarily use the external Codex bridge instead, override the executable and put every argument in extraArgs:

  provider:
    type: codex
    cmd: npx
    extraArgs:
      - -y
      - '@normahq/[email protected]'

See the runnable reviewer example.

Script

---
apiVersion: callee.metalagman.dev/v1alpha1
kind: Script
spec:
  description: Runs a local validator.
  shell: sh
  onNonZero: continue
---
go test ./...

Script runs a local validator step through sh or bash, captures stdout and stderr, and records structured results in .State.scripts[effectiveId]. Use onNonZero: fail for hard gates and onNonZero: continue when a later node should inspect the failure and decide what to do next.

Human

---
apiVersion: callee.metalagman.dev/v1alpha1
kind: Human
spec:
  description: Requests operator approval.
  responseKey: approval
---
Review and approve this request:
{{ .Input }}

In interactive mode, Human renders its body on the controlling TTY and waits for one nonblank operator response. The response becomes the node artifact, is promoted to .State.outputs[effectiveId], and is also stored at the top-level state key selected by responseKey; outputs and scripts are reserved response keys. A Human has no provider, permissions, parameters, or REPL setting. Its presence makes the spec-driven whole-agent mode interactive; explicitly selecting non-interactive mode fails during preflight, even for an unselected Router branch.

Sequential

---
apiVersion: callee.metalagman.dev/v1alpha1
kind: Sequential
spec:
  description: Plans, implements, and validates.
  children:
    - ref: roles/planner
      alias: planner
    - ref: roles/implementer
      alias: implementer
      input: |
        Plan:
        {{ .State.outputs.planner }}
    - ref: roles/reviewer
      alias: validator
  output: |
    {{ .State.outputs.validator }}
---
{{ .Input }}

Sequential runs children in source order. Without an explicit child input, the first child receives the composite input and later children receive their predecessor's output. Escalation is sticky across the remaining sequential children and propagates upward after they finish. See the runnable investigate example.

Loop

---
apiVersion: callee.metalagman.dev/v1alpha1
kind: Loop
spec:
  description: Repeats a worker and validator until the validator escalates.
  children:
    - ref: roles/implementer
      alias: worker
      input: |
        Goal:
        {{ .Input }}

        {{ with index .State.outputs "validator" }}
        Previous validation:
        {{ . }}
        {{ end }}
    - ref: roles/reviewer
      alias: validator
      canEscalate: true
      input: |
        Goal:
        {{ .Input }}

        Worker result:
        {{ .State.outputs.worker }}

        Validate the result. If it satisfies the goal, return your validation
        and escalate to finish the loop. Otherwise return actionable feedback
        normally so the next iteration can improve it.
  maxIterations: 5
  onExhausted: fail
  output: |
    GoalKeeper finished with result:
    {{ .State.outputs.validator }}
---
{{ .Input }}

A Loop repeats its ordered children up to maxIterations. A normal Role return is a recoverable result: the Loop continues through its remaining children and later iterations. An authorized escalation returned by a direct child completes the Loop immediately and skips later Loop children; a nested Sequential first finishes its own remaining children before propagating sticky escalation. Set canEscalate: true on every edge from the nearest Loop to the Role that may finish it; omitted values default to false. Reserve fail for unrecoverable conditions because it aborts the entire workflow. onExhausted is fail by default or may be complete. Parallel is not part of v1alpha1. See the runnable goalkeeper example.

Router

---
apiVersion: callee.metalagman.dev/v1alpha1
kind: Router
spec:
  description: Routes one classified task to exactly one handler.
  route: '{{ .Input }}'
  children:
    - ref: roles/implementer
      alias: routed_implementer
      route: implement
    - ref: roles/reviewer
      alias: routed_reviewer
      route: review
    - ref: roles/explorer
      alias: routed_generalist
      default: true
---
{{ .Prompt }}

A Router renders spec.route to choose exactly one child, then renders its Markdown body independently as that child's payload. The trimmed route key matches named children[].route values case-sensitively. An optional default: true child handles only blank or unknown keys; without it, no-match fails before any child starts. A route-template error never selects default, and failure after a child is selected never retries or fails over. Router edges use mapping form and declare exactly one of route or default: true. See the runnable classifier, task-router, and composed routed-task examples.

Children and composition

Children may reference any supported kind, including another composite. A child mapping supports ref, optional globally unique alias, canEscalate, input, shallow state, and Role-only params. Router children additionally require exactly one unique named route or the sole default: true edge. Aliases match ^[a-z][a-z0-9_]*$ and replace the occurrence's effective ID. canEscalate is occurrence-specific, so two aliases of the same Role may have different authority.

YAML representation and JSON Schema

Markdown is the canonical authoring format: its physical body becomes spec.body and spec.body must not also appear in frontmatter. A .yaml or .yml file represents the same complete resource object and must author spec.body inline.

Callee validates both representations against the checked-in Draft 2020-12 JSON Schema, whose exact bytes are embedded in the binary. Use callee agent schema <Role|Script|Human|Sequential|Loop|Router> when you want a standalone schema document for one kind. For editor integration, use the raw schema from the repository:

# yaml-language-server: $schema=https://raw.githubusercontent.com/baldaworks/callee/main/internal/agent/schema.json
apiVersion: callee.metalagman.dev/v1alpha1
kind: Role
spec:
  description: Reviews changes.
  provider:
    type: codex
  permissions:
    mode: ask
  params:
    focus: Review focus
  body: |
    You are a reviewer.

    Task:
    {{ .Input }}

    Focus:
    {{ .Params.focus }}

This YAML object is canonically identical to the Markdown Role above. The same representation rule applies to every supported kind.

agent validate performs schema, semantic, state, and template validation for exactly one file. It intentionally does not resolve workflow child references; use agent view <id> or doctor to validate the discovered graph.

Templates and state

All workflow-aware surfaces use Go text/template with missingkey=zero, a pinned deterministic Sprig v3.3.0 positive allowlist, and strict explicit-input UTC dateParse/dateFormat helpers. Environment, filesystem, network, clock, random, UUID, crypto-generation, and mutating dictionary helpers are unavailable.

The common template root exposes:

• .Prompt: immutable original user prompt.
• .Input: current node input.
• .State: one JSON-compatible root-run state object.
• .Params: current Role parameter map.
• .Output: natural child-derived output, only while rendering composite spec.output.

Every successful nonblank node artifact is promoted to .State.outputs[effectiveId]. Script also records its detailed validator result at .State.scripts[effectiveId], including status, exitCode, stdout, stderr, and timedOut. The engine owns both outputs and scripts; authored state cannot replace either key. Repeated visits use last-successful-write-wins.

State modifiers are shallow top-level replacements. String leaves are templates evaluated against one pre-node snapshot, and the complete modifier commits atomically.

Runtime parameters

spec.params declares required Role inputs and their descriptions. A direct Role uses its resource ID as the effective node ID; a child alias replaces that ID for one workflow occurrence. callee agent view <agent-id> reports every unbound parameter using the required <effective-node-id>.<name> key.

For example, after saving the Role example above as .callee/roles/focused-reviewer.md:

callee agent view roles/focused-reviewer
callee agent run roles/focused-reviewer \
  --message "Review the current changes" \
  --param roles/focused-reviewer.focus=security

Repeat --param for literal values. Use --param-file <effective-node-id>.<name>=<path> for exact multiline file contents; stdin (-) is not accepted. Parameters bound by a composite child's params mapping are omitted from the runtime requirements. If a required value is not supplied by a flag, interactive mode asks through the controlling terminal immediately before that Role runs. Non-interactive mode reports all missing required keys before provider startup.

Control and REPL

Set spec.interactive: true only on a Role that needs multiple operator turns in one provider session. Composite agents do not have a REPL field. PromptKit generation also enables this field automatically for templates whose metadata.mode is interactive, or explicitly with callee promptkit role create ... --interactive.

At execution time, callee agent run --interactive=true|false overrides the authored setting for every Role visit in that run. true selects the REPL protocol and false selects one-shot artifact responses; omitting the flag preserves each Role's authored setting. --permissions remains an independent ACP policy axis; --interactive=true is compatible with every permission mode, while --interactive=false requires effective allow or deny. This is separate from PromptKit's author-time promptkit role create ... --interactive flag.

Callee injects a versioned control protocol into every executed Role. Every REPL turn must end with exactly one final record:

callee.control.v1.await
callee.control.v1.return
callee.control.v1.escalate
callee.control.v1.fail

Artifact text, when present, is separated from the record by exactly one empty line. await requires question text and retains the same visit session for another operator turn. return requires an artifact and completes normally. escalate is available only to a Role whose path to the nearest Loop sets canEscalate: true on every edge, and it returns control to that Loop. Inside a Loop, return is the recoverable choice and lets normal Loop execution continue. fail aborts the entire workflow and is reserved for unrecoverable conditions.

Every Role visit starts a fresh provider session, including repeated Loop visits; only await turns within one REPL visit reuse a session. A prepared REPL visit emits one entering repl / exiting repl lifecycle pair, with all await turns inside it. Interactive mode uses the controlling TTY for initial input, missing parameters, Human responses, permission choices, and REPL turns. Fully supplied, one-shot, automatic, Human-free runs do not open the TTY. The default maximum wait for each operator prompt is 30m; change it with --repl-timeout. Hosts must answer on the TTY and must not send /done, quit, or exit to choose completion.

Human smoke test

The repository includes PTY-backed smoke tests that run the current checkout against an exclusive fixture catalog:

./scripts/smoke-test-callee-human.sh questions
./scripts/smoke-test-callee-human.sh loop

questions needs no provider. loop uses the configured Codex ACP runtime to verify that a normal Role return continues into a Human response, that the response reaches shared state, and that the Loop starts Role visit 2. It then stops intentionally instead of waiting for the fixture Loop to converge. The Codex CLI must be installed and authenticated, with writable $CODEX_HOME or ~/.codex. Pass --keep-temp to retain artifacts and diagnostics under /tmp.

Doctor and graphs

callee doctor
callee doctor --timeout 90s
callee doctor --graph text
callee doctor --graph mermaid
callee doctor --graph dot

Plain doctor completes static schema/template/graph validation before provider startup, groups Roles by provider process identity, checks ACP initialization and disposable session creation, and sends no model prompt. Graph modes are static-only and never start providers.

PromptKit

Callee embeds the pinned PromptKit catalog through PromptKitty:

callee promptkit list
callee promptkit search "write requirements document" --type template
callee promptkit show review-code
callee promptkit role create go-reviewer \
  --template review-code \
  --description "Reviews Go code" \
  --provider codex \
  --prompt-param code \
  --bind language=Go

search uses PromptKitty's deterministic, in-memory BM25 index from vecgo. It ranks component names, descriptions, metadata, and complete Markdown bodies with weights 4 / 2 / 1 / 1, while preserving the existing table and JSON component shapes. Callee exposes catalog list, search, and show commands plus its own role create; PromptKitty's standalone assemble and setup commands are not mounted.

Generated Roles use the v1alpha1 envelope and Go templates. Unbound PromptKit parameters become spec.params; literal template examples in assembled PromptKit text are escaped safely. A template whose metadata.mode is interactive automatically generates spec.interactive: true, so its questions and confirmation gates run through the same provider session when the Role is executed. Use callee promptkit role create ... --interactive to force that authoring behavior for an ordinary template.

Unless --output is supplied, role create go-reviewer writes .callee/roles/go-reviewer.md; it creates parent directories but refuses to replace an existing file unless --force is set. --dry-run prints the generated Markdown without writing it. The parameter selected by --prompt-param is filled from the root message. --bind and --bind-file freeze author-time values; every other declared template parameter becomes a runtime spec.params entry. A configurable persona must be supplied with --persona, not through the parameter flags.

Distribution and limits

The npm distribution uses CGO-disabled native executables for macOS and Linux on AMD64/ARM64 and Windows AMD64 behind the @baldaworks/callee launcher. Each root run is ephemeral: no Callee thread store, persisted workflow state, server transport, or cross-process continuation is created.

License

Callee is released under the MIT License. See Third-party notices for embedded and statically linked dependencies.

OpenAI Build Week

Callee was built during OpenAI Build Week using Codex and GPT-5.6 as the primary development system. The project was directed by a human operator, but the implementation loop, design iteration, CLI behavior, workflow semantics, graph tooling, setup flows, examples, and documentation were produced through sustained collaboration with Codex and GPT-5.6.

Codex and GPT-5.6 were used to:

• design the Role, Script, Human, Sequential, Loop, and Router agent model;
• implement CLI commands, runtime behavior, and validation flows;
• build graph inspection, doctor checks, and setup integrations;
• create starter agents, examples, and user-facing documentation;
• refine repository UX, packaging, and release-facing presentation.

The human role remained product direction, architecture review, scope control, and final acceptance of what shipped.