seihou-cli-0.8.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.

      --mark-applied records every pending edge in the window as already
      applied, without running them, on your assertion that you performed the
      upgrade by hand. No provider is contacted and no file in the working
      tree is changed. Each receipt is filed under the blueprint that owns its
      edge, so a marked entailed edge suppresses a later direct run of that
      blueprint too; edges that already have receipts are left alone rather
      than restamped. --rerun clears a mistaken marking. The flag is refused
      alongside --rerun or parent --debug, both of which it contradicts.

      A receipt records that an edge has been dealt with -- a provider
      interaction returned, or you marked it -- 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