seihou-cli-0.7.0.0: help/agent.md

AGENT COMMANDS

`seihou agent` renders Seihou-aware prompts and starts a configured
provider. The agent commands are for AI-assisted
module authoring, bootstrapping, project setup, running agent-driven
blueprints, and applying ordered blueprint library migrations.

CLI providers open interactive local Claude Code or Codex sessions.
API providers send one rendered prompt as a batch completion and print
one assistant response.

USAGE

  seihou agent [--debug] [--provider PROVIDER] [--model MODEL] <subcommand> [options]

PARENT OPTIONS

  --debug
      Print the resolved system prompt and exit without contacting any
      provider. Use this to inspect what Seihou would send.

  --provider PROVIDER
      Select the provider for this invocation. Accepted values:
      `claude-cli`, `codex-cli`, `anthropic`, `openai`.

  --model MODEL
      Select a provider-specific model name or alias for this
      invocation. Run `seihou agent models` to list known choices.

Provider and model options may appear on the parent command or on the
subcommand:

  seihou agent --provider codex-cli --model gpt-5 assist "create a module"
  seihou agent assist --provider codex-cli --model gpt-5 "create a module"
  seihou agent --debug --provider openai setup "inspect this prompt"

PROVIDERS

  claude-cli
      Starts an interactive Claude Code session. Requires the
      `claude` binary on PATH and a working local login. With no
      explicit model, the CLI chooses its own default.

  codex-cli
      Starts an interactive Codex session. Requires the `codex`
      binary on PATH and a working local login. With no explicit
      model, the CLI chooses its own default. Seihou launches Codex
      with workspace-write sandboxing and on-request approvals.

  anthropic
      Uses the Anthropic Messages API. Requires `ANTHROPIC_API_KEY`
      or `ANTHROPIC_KEY`. Defaults to `claude-sonnet-4-6` when no
      model is configured.

  openai
      Uses the OpenAI Chat Completions API. Requires `OPENAI_API_KEY`
      or `OPENAI_KEY`. Defaults to `gpt-4o-mini` when no model is
      configured.

CONFIGURATION

Provider and model values resolve independently from module variables.
The first non-blank value wins:

  1. Subcommand CLI flags: `--provider`, `--model`
  2. Parent CLI flags: `--provider`, `--model`
  3. Environment: `SEIHOU_AGENT_PROVIDER`, `SEIHOU_AGENT_MODEL`
  4. Local config: `.seihou/config.dhall`
  5. Global config: `~/.config/seihou/config.dhall`
  6. Built-in defaults: provider `claude-cli`, no explicit model

Set personal defaults globally:

  seihou config set agent.provider codex-cli --global
  seihou config set agent.model gpt-5 --global

Use environment variables for a temporary shell session:

  export SEIHOU_AGENT_PROVIDER=openai
  export SEIHOU_AGENT_MODEL=gpt-4o-mini

SUBCOMMANDS

  seihou agent models [--provider PROVIDER]
      List the Anthropic and OpenAI models in Seihou's compiled Baikai
      catalog. Filtering by `anthropic` or `claude-cli` returns the same
      Claude-family models; filtering by `openai` or `codex-cli` returns
      the same OpenAI-family models. The filter may appear before or
      after `models`:

        seihou agent --provider claude-cli models
        seihou agent models --provider openai

      Listing models requires no provider credentials, network access,
      or agent configuration. The catalog is a discovery aid, not
      validation: provider-native aliases and custom model IDs remain
      accepted by `--model`. Do not pass `--model` to this listing
      command.

  seihou agent assist [PROMPT]
      Render a prompt for creating or modifying Seihou modules. The
      prompt includes current project context, available modules, and
      the module schema.

  seihou agent bootstrap [PROMPT] [--repo]
      Render a prompt for creating a new module from scratch. With
      `--repo`, target a multi-module repository with
      `seihou-registry.dhall`.

  seihou agent setup [PROMPT]
      Render a prompt for using existing Seihou modules in a project:
      selecting modules, configuring variables, previewing, running,
      verifying, and committing.

  seihou agent run BLUEPRINT [PROMPT] [--var KEY=VALUE] [--no-baseline]
      Resolve a blueprint, optionally apply its baseline modules,
      render the blueprint prompt, and send it to the configured
      provider. A successful non-debug run records applied-blueprint
      provenance in `.seihou/manifest.json`.

  seihou agent migrate BLUEPRINT [--from VERSION] [--to VERSION] [PROMPT]
      Run one agent session per in-window migration declared by the blueprint.
      Versions are dotted numbers; gaps are allowed. Successful edges are
      recorded immediately so a later invocation resumes at the first
      unrecorded edge. `--rerun` ignores matching receipts. Migration mode does
      not apply baseModules and exposes neither --no-baseline nor --force.

      Either end of the window may be omitted. --to then comes from the
      blueprint's declared versionProbe, a command it supplies that reads the
      version this project depends on; --from comes from the highest version
      already recorded in this project's receipts. An explicit flag always
      wins, and an inferred end is reported with the source it came from.

      Parent --debug prints every pending migration prompt in order without
      contacting a provider or writing receipts. It does run the version
      probe, which is required to be read-only, so debug planning matches a
      real run. A receipt records provider completion, not package-manager
      verification.

  seihou prompt run PROMPT [USER-PROMPT] [--var KEY=VALUE] [--debug]
      Resolve a reusable prompt, run command-derived variables, render
      the prompt body, and send it to the configured provider. Prompts
      do not apply blueprint baselines or record blueprint provenance.

DEBUG EXAMPLES

  seihou agent --debug --provider claude-cli assist "inspect this prompt"
  seihou agent --debug --provider codex-cli bootstrap --repo "inspect this prompt"
  seihou agent --debug --provider openai setup "inspect this prompt"
  seihou agent --debug run my-blueprint --var project.name=demo
  seihou agent --debug migrate my-library --from 1.0.0 --to 3.0.0
  seihou agent --debug migrate my-library

SEE ALSO

  seihou agent --help
  seihou help config
  seihou help variables
  seihou help prompts
  docs/cli/agent.md
  docs/user/config-and-variables.md