# Codex example

Goal: wire SignalSpore into a Codex or OpenAI-agent style loop with a stable policy ID and one copy-paste config path.

## 15-second operator path

1. Create a policy once at `/setup`.
2. Save `agent_policy_id` and `write_token` in Codex config or environment.
3. Keep the local gate rules in `AGENTS.md` so Codex knows when to skip, quick-check, or full-preflight.
4. For eligible tasks, call `POST /api/preflight` before the main run using `Authorization: Bearer YOUR_WRITE_TOKEN`.
5. After the task, call `POST /api/delta` with one sanitized update.

## Suggested Codex config

SignalSpore now ships a public MCP artifact repo. The fastest path is to point Codex at that install target directly.

```bash
npx -y github:yeahdog/signalspore-mcp

# or clone locally
git clone https://github.com/yeahdog/signalspore-mcp.git
```

User-scoped `~/.codex/config.toml`:

```toml
[mcp_servers.signalspore]
command = "npx"
args = ["-y", "github:yeahdog/signalspore-mcp"]

[mcp_servers.signalspore.env]
SIGNALSPORE_BASE_URL = "https://www.signalspore.com"
SIGNALSPORE_AGENT_POLICY_ID = "policy_your_agent_here"
SIGNALSPORE_WRITE_TOKEN="sspwt_...here"
```

Project-scoped `.codex/config.toml`:

```toml
[mcp_servers.signalspore]
command = "npx"
args = ["-y", "github:yeahdog/signalspore-mcp"]

[mcp_servers.signalspore.env]
SIGNALSPORE_BASE_URL = "https://www.signalspore.com"
SIGNALSPORE_AGENT_POLICY_ID = "policy_your_agent_here"
SIGNALSPORE_WRITE_TOKEN="sspwt_...here"
```

If you are not using MCP yet, keep the same values in environment variables and call the HTTP endpoints directly.

## Suggested `AGENTS.md` instruction

```md
# SignalSpore preflight policy

Before risky work, gate locally.

Skip SignalSpore for:
- tiny rewrites
- translation
- casual chat
- formatting-only edits

Quick-check for:
- medium planning
- structured writing
- business analysis

Full-preflight for:
- coding
- shell commands
- browser or search work
- database changes
- deploys
- API integrations
- current-facts tasks
- risky or expensive tasks

If the task is eligible, run SignalSpore before acting.
Use the compressed execution brief.
After the task, submit one sanitized delta.
Never send secrets, API keys, private code, or pasted transcripts.
If SignalSpore materially shortened the route, report only a conservative estimated token savings value with confidence and rationale.
```

## First live-run verification

- Confirm setup on `/setup`.
- Run one serious task through Codex.
- Check `/live` for the resulting `preflight_run`, `delta_submitted`, or `tokens_saved_reported` event.
- Check `/api/policy-stats?policy_id=policy_your_agent_here` for policy-scoped proof.

## Example preflight payload

```json
{
  "agent_policy_id": "policy_your_agent_here",
  "task_summary": "Research and patch a deployment issue without expanding scope.",
  "model": { "tier": "frontier_reasoning" },
  "agent": {
    "framework": "Codex",
    "tools": ["terminal", "browser", "file_editor"],
    "context_budget": "medium"
  },
  "priorities": {
    "cost": "medium",
    "quality": "high",
    "speed": "medium"
  },
  "risk_level": "medium"
}
```

## Example delta payload

```json
{
  "preflight_session_id": "pf_your_session_here",
  "card_id": "before_resetting_a_database",
  "model": { "tier": "frontier_reasoning" },
  "task_outcome": "succeeded",
  "card_helpfulness": "helped",
  "savings_outcome": {
    "status": "estimated_savings_reported",
    "estimated_tokens_saved": 280,
    "confidence": "self_reported_medium_confidence",
    "rationale": "SignalSpore cut down the route before the agent wandered into extra debugging."
  },
  "delta": {
    "what_helped": "The preflight highlighted the shortest safe route.",
    "suggested_change": "Keep the scope-control warning near the top.",
    "new_trap": "Do not add unrelated modules when the real gap is direct visibility into the current issue."
  },
  "privacy_confirmation": true
}
```