# ForecastOS — Agent install instructions

Install ForecastOS so your agent can search prediction markets, draft multi-outcome specs, and advance reviewable workflows on [Precog](https://precog.markets).

## Prerequisites

- **Git** — to clone the repository
- **Node.js** (v18+) — to build the optional MCP server and run validation scripts
- **Repo:** https://github.com/precog-markets/forecast-os

## Clone the repository

```bash
git clone https://github.com/precog-markets/forecast-os.git
cd forecast-os
```

Set `REPO_ROOT` to your clone path for the commands below. Examples use `/path/to/forecast-os` — replace it everywhere.

## Detect your agent host

ForecastOS supports **Cursor**, **Codex**, **Claude Code**, and **Hermes**. Identify which host you are running, then follow the matching sections below.

---

## Step 1: Install the skill

Install the ForecastOS skill as a persistent skill in your host's skills directory.

> **Windows:** use a directory junction (`mklink /J`) or copy the adapter folder instead of `ln -s`. See the repo README for details.

### Cursor

```bash
ln -s /path/to/forecast-os/adapters/hosts/cursor/forecast-os ~/.cursor/skills/forecast-os
```

### Codex

```bash
ln -s /path/to/forecast-os/skill/forecast-os ~/.codex/skills/forecast-os
```

### Claude Code

```bash
ln -s /path/to/forecast-os/adapters/hosts/claude/forecast-os ~/.claude/skills/forecast-os
```

### Hermes

```bash
mkdir -p ~/.hermes/skills/prediction
ln -s /path/to/forecast-os/adapters/hosts/hermes/skills/prediction/forecast-os ~/.hermes/skills/prediction/forecast-os
```

Reload or restart your agent host after symlinking.

---

## Step 2: Optional — connect the read-only MCP

The MCP server provides read-only context: templates, schemas, examples, and live Precog capabilities. It does **not** sign transactions or custody wallets.

### Build the MCP server

From the repo root:

```bash
cd mcp/forecast-os-mcp-server && npm install && npm run build
```

### Cursor

Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project). Replace the repo path, then restart Cursor and open **Settings → MCP** to confirm `forecastos` is active.

```json
{
  "mcpServers": {
    "forecastos": {
      "command": "node",
      "args": ["/path/to/forecast-os/mcp/forecast-os-mcp-server/dist/stdio.js"],
      "env": {
        "FORECASTOS_STATE_DIR": "/path/to/forecast-os/skill/forecast-os/.forecastos"
      }
    }
  }
}
```

### Codex

Merge into your Codex MCP config using the pattern from `adapters/hosts/codex/mcp.json`. Replace the repo path before starting Codex.

```json
{
  "servers": {
    "forecastos": {
      "command": "node",
      "args": ["/path/to/forecast-os/mcp/forecast-os-mcp-server/dist/stdio.js"],
      "env": {
        "FORECASTOS_STATE_DIR": "/path/to/forecast-os/skill/forecast-os/.forecastos"
      }
    }
  }
}
```

### Claude Code

Copy `adapters/hosts/claude/.mcp.json` to the project root Claude Code opens. Set `FORECASTOS_REPO_ROOT` to your clone path if the file is not at the repo root.

```json
{
  "mcpServers": {
    "forecastos": {
      "command": "node",
      "args": ["${FORECASTOS_REPO_ROOT:-.}/mcp/forecast-os-mcp-server/dist/stdio.js"],
      "env": {
        "FORECASTOS_STATE_DIR": "${FORECASTOS_REPO_ROOT:-.}/skill/forecast-os/.forecastos"
      }
    }
  }
}
```

Claude Code prompts for approval before using project-scoped MCP servers.

### Hermes

Hermes is skill-first. MCP is optional read-only context — configure `mcp_servers` in `~/.hermes/config.yaml` after building the server, or paste this into your agent:

```
Install the ForecastOS read-only MCP from https://github.com/precog-markets/forecast-os. Build mcp/forecast-os-mcp-server, then wire the stdio server using adapters/hosts and report when tools are available.
```

---

## Step 3: Verify

From the repo root, run the validation scripts for your host.

### Cursor

```bash
cd skill/forecast-os && node scripts/validate_skill.mjs
node adapters/hosts/cursor/forecast-os/scripts/check-cursor-setup.mjs
```

### Codex

```bash
cd skill/forecast-os && node scripts/validate_skill.mjs
```

### Claude Code

```bash
cd skill/forecast-os && node scripts/validate_skill.mjs
node adapters/hosts/claude/forecast-os/scripts/check-claude-setup.mjs
```

### Hermes

```bash
cd skill/forecast-os && node scripts/validate_skill.mjs
node adapters/hosts/hermes/skills/prediction/forecast-os/scripts/check-hermes-setup.mjs
```

Report any failures and what you fixed.

---

## Step 4: Try it

Ask your assistant:

- Is there a prediction market about [topic]? Search before guessing.
- Who's going to win the 2026 World Cup? Check live markets on Precog.
- Draft a multi-outcome Precog market for [decision question].
- Consume_prediction from an existing deployed market and summarize live odds.

---

## Step 5: Wallet (optional)

Live create, fund, and trade need a wallet provider after ForecastOS is installed. Pick one and follow its setup guide:

- **Privy** — [github.com/privy-io/privy-agentic-wallets-skill](https://github.com/privy-io/privy-agentic-wallets-skill)
- **Bankr** — [Bankr SKILL.md](https://github.com/BankrBot/skills/blob/main/bankr/SKILL.md)
- **Base** — [docs.base.org/agents/quickstart](https://docs.base.org/agents/quickstart)

Step-by-step copy blocks for each provider: `/#wallets` on the ForecastOS landing site.

---

## Safety rules

- **MCP stays read-only** — no wallet custody, no signing, no live spending.
- **Live create, fund, and trade require operator approval** — the skill routes action intents for human review before anything hits chain.
- Follow the repo README and skill safety rules at all times.

---

## Report back

Tell your operator:

1. Which host you detected and what you installed (skill, MCP, or both)
2. Validation results from Step 3
3. What still needs operator approval before live create, fund, or trade

Full docs: https://github.com/precog-markets/forecast-os