A Codex-Style Multi-Agent CLI for Automated Physics Experiment Report Writing

English | 中文

A codex-style, multi-agent command-line tool for automatically writing physics-experiment reports in LaTeX or Typst. It is a Rust rewrite of the AutoReport desktop app — no GUI, no MCP, no image recognition. The terminal is the interface; the working directory is the project.

╭────────────────────────────────────────────────────╮
│ >_ AutoReportCLI (v0.1.3)                          │
│                                                    │
│ model: gpt-5   /model to change                    │
│ directory: ~/my-experiment                         │
╰────────────────────────────────────────────────────╯

Tip: use /agent to switch report roles, or @ to add a data or reference file.
Five specialised agents are ready. Tab switches focus; every agent keeps its own history.
  To get started, describe a task or try one of these commands:
  /agent - switch report roles or add a data/reference file
  /switch - focus a specific agent
  /manifest - show session configuration
  /pager - browse the full transcript
  /ide - toggle IDE context

› Implement {feature}
gpt-5 · ~/my-experiment

Overview

AutoReportCLI keeps the multi-agent workflow of AutoReport, but rebuilds it as a terminal-first tool in Rust. You work inside an experiment folder, feed in raw data and references, and coordinate five agents from a single codex-style TUI.

Features

Core Capabilities

• Multi-Agent Collaboration — Main, Theory, Data Analysis, Plotting, and Report agents work on the same experiment with separate responsibilities and write boundaries
• Project-Oriented Workspace — each run operates on the current folder and creates the standard report layout automatically
• LaTeX and Typst Reports — supports language selection, bundled templates/themes, bibliography assets, report compilation, and Python-based analysis and plotting
• Provider Flexibility — supports Anthropic, OpenAI-compatible, OpenAI Responses, DeepSeek, OpenRouter, Google-compatible, and custom providers, with separate Main/sub-agent model bindings
• Resource Synchronization — syncs provider presets and report-writing skills on startup; use --no-sync for cached resources or --sync-presets to refresh them
• Task and Artifact Tracking — bounded delegation, task-board updates, produced-file manifests, and per-agent persistent sessions keep the report workflow inspectable
• Safe Execution — report-specific exec policy and cross-platform sandboxing protect agent writes; network access is denied by default
• Built-In Defaults — ships bundled report templates, themes, and skills so a fresh workspace can run immediately

TUI Experience

• Codex-Style Interface — full-screen terminal UI with streaming output, Markdown rendering, agent status, pagers, resize reflow, and keyboard-first navigation
• Agent Navigation — Tab / Shift+Tab, /agent, and /switch <agent> change the focused role while preserving each agent's transcript
• OSC-8 Hyperlinks — file paths and web links render as clickable terminal hyperlinks; generated visualizations can open in a browser
• Composer History Search — Ctrl+R / Ctrl+S reverse- and forward-i-search through prior inputs, codex-style
• Per-Turn Metrics — tool/inference counts and elapsed time are shown on completed turn separators
• Codex Approval Prompts — command approvals use the default keymap (y / a / p / d / Esc / n / c), which can be configured
• Persistent Agent Sessions — each agent keeps its own conversation history and resumes on the next launch
• @ File Mentions — fuzzy-search workspace files and inject them into prompts directly from the input box
• Slash Commands — /agent, /resume, /config, /model, /env, /compact, /pager, /clear, /copy, /manifest, /index, /ide, and /quit (legacy aliases such as /agents, /sessions, and /new remain accepted)
• IDE Context — /ide toggles context injection from a compatible local IDE integration when available

Quick Start

Prerequisites: Rust 1.85+, a TeX distribution, and at least one LLM provider API key.

Build from source:

git clone <this-repo> AutoReportCLI && cd AutoReportCLI
cargo build --locked --release

For the fastest development loop, use cargo run -p autoreport-cli or cargo build -p autoreport-cli. Formal release payloads use the separate dist profile:

cargo build --locked --profile dist -p autoreport-cli

To inspect compilation time by crate, add --timings; Cargo writes the report to target/cargo-timings/cargo-timing.html. Avoid running cargo clean before every build, because that removes the cache the next build would reuse.

Install globally if you want autoreport available from any directory:

cargo install --locked --path autoreport-rs/cli

On Linux, install the companion sandbox launcher into the same Cargo bin directory as well. Restricted exec commands fail closed if it is absent:

cargo install --locked --path autoreport-rs/linux-sandbox

Or run the built binary directly:

./target/release/autoreport

Create a project folder and start:

mkdir ~/my-experiment && cd ~/my-experiment
autoreport

If autoreport is not in your PATH, use the binary path instead:

/path/to/AutoReportCLI/target/release/autoreport

On first launch, AutoReportCLI synchronizes cached presets and skills, configures the API and Main/sub-agent models, selects the global Python environment and the project's LaTeX/Typst language, asks you to confirm the workspace, then creates the workspace folders and opens the TUI. Built-in templates and synced presets/skills live in the global AutoReport home. Existing project files are not overwritten during resource materialization.

Configuration

Configure a provider in any of these ways:

• Set an API key environment variable such as ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, OPENROUTER_API_KEY, or GEMINI_API_KEY
• Copy autoreport.config.example.toml to $AUTOREPORT_HOME/config.toml (default: ~/.autoreport/config.toml), or use /config and /model. AUTOREPORT_HOME can point to another global AutoReport home.
• Use /config to edit provider API entries, /model to bind Main and the shared specialist model, and /env to configure Python and the current project's LaTeX/Typst language.
• Let the first-run full-screen setup page guide you through provider selection and saving

Useful CLI flags:

• --workspace <dir> to run on a different project folder
• --no-sync to skip startup sync and use cache only
• --sync-presets to force a refresh and exit
• --reset to clear AutoReport configuration (config.toml, auth.json, and environment.toml) without touching sessions, history, rollouts, logs, or user-provided resources
• --log to opt into the durable TUI log and logs_2.sqlite
• -v for verbose stderr diagnostics only; it does not enable file logging

Rollout trace bundles are a separate opt-in diagnostic channel. Set CODEX_ROLLOUT_TRACE_ROOT to enable them; this is independent of --log. Without --log, diagnostics stay on stderr and no durable TUI log or SQLite log database is created.

Workspace Layout

.
├── Data/            raw data and processed results
├── References/      papers, images, templates, custom skills
├── Theory/          theory agent output
├── Plots/           plotting figures (Plots/Fig) and scripts (Plots/Scripts)
├── Report/             active LaTeX/Typst sources and compiled PDF
├── Outline/         main agent planning output
└── (no AutoReport metadata files; program state lives in ~/.autoreport/)

Global program state follows Codex's home-directory model:

~/.autoreport/
├── config.toml
├── auth.json         provider credentials (mode 0600 where supported)
├── history.jsonl                       append-only conversation history
├── environment.toml                    global Python environment
├── venv/                               AutoReport-managed Python environment (optional)
├── resources/       language-specific bundled and synced skills/templates/themes
├── external/providers/  synced provider presets
└── workspaces/<id>/                    manifests, rules, project.toml, metadata

Development

The Rust source follows Codex's workspace layout rather than a monolithic src/ tree:

autoreport-rs/
├── cli/                  executable entry point
├── core/                 configuration, providers, agents, skills, domain types
├── runtime/              persistent agent loops and orchestration
├── tui/                  terminal UI, OSC-8 rendering, IDE context
├── tools/                tool definitions and local handlers
├── shell-command/        codex-aligned shell/exec parsing
├── protocol/             shared policy and sandbox protocol types
├── codex-protocol/       vendored Codex protocol types (from codex-rs)
├── app-server-protocol/  vendored app-server protocol + schema fixtures
├── app-server-transport/ stdio / unix-socket / websocket transport
├── uds/                  Unix domain socket transport
├── rollout/              Codex-compatible session persistence
├── sandboxing/           cross-platform execution policy (seatbelt / bwrap / landlock)
├── linux-sandbox/        Linux sandbox launcher (bwrap + seccomp)
├── bwrap/ · windows-sandbox/   platform sandbox helpers
├── network-proxy/        managed network proxy and MITM policy
├── execpolicy/           starlark exec-policy rule engine
└── utils/                absolute-path, path-uri, home-dir, pty, image, …

Run tests with:

cargo test --locked

CI (/.github/workflows/ci.yml) uses one platform matrix: pull requests run formatting, Linux lint/tests, and native macOS/Windows checks. Pushes to main, version tags, and manual runs additionally build and verify the Linux musl, macOS, and Windows npm payloads. Release packaging is therefore not part of the pull-request path.

Build an npm package with a native binary for the current Rust target:

npm run build:npm
(cd autoreport-cli && npm pack --dry-run)

For implementation status and parity notes, see docs/PARITY.md. The product boundary and intentional Codex divergences are recorded in docs/own-features.md.