Skip to content
BranchesTags

Repository files navigation

Polyagent

Polyagent is a Claude Code native research and execution environment for Polymarket.

The repository is organized around three rules:

  • Claude Code owns research, synthesis, and order expression
  • MCP servers expose capability without embedding strategy opinion
  • APIs and UI persist artifacts, runtime state, schedules, and replayable execution records

Components

  • services/artifact-api Structured journal for artifacts, linked sessions, and execution records.
  • services/artifact-mcp Thin MCP wrapper over artifact-api so Claude can read and write journal state directly.
  • services/supervisor Session orchestration layer that runs the native claude CLI with persistent session ids, cron schedules, and trigger records.
  • services/supervisor-mcp Thin MCP wrapper over supervisor so Claude can manage sessions, schedules, and trigger programs directly.
  • services/polymarket-mcp Thin MCP server that wraps Polymarket Gamma/CLOB reads and live order operations.
  • apps/audit-ui Mobile-aware research terminal for theses, sessions, schedules, triggers, and execution journals.
  • .claude Project policy layer for skills, commands, agents, and memory.

Documentation

Runtime Model

  • supervisor invokes claude -p with persistent --session-id values.
  • Docker supervisor runs as a non-root user so Claude Code can use bypassPermissions with --dangerously-skip-permissions.
  • .mcp.json and .mcp.docker.json mount the local MCP servers into those Claude sessions.
  • Schedules are infra-level cron jobs; prompts remain agent-defined.
  • The codebase does not contain a backend-owned alpha engine.

System Structure

Control Plane

  • services/supervisor Owns Claude Code session lifecycle, prompt dispatch, cron schedules, trigger metadata, and runtime health.
  • services/artifact-api Owns durable structured state for artifact, research_session, and execution_record.

Tool Plane

  • services/artifact-mcp Claude-facing MCP server for journal operations.
  • services/supervisor-mcp Claude-facing MCP server for session lifecycle, schedule management, and trigger programming.
  • services/polymarket-mcp Thin MCP tool server for Polymarket market reads and live order actions.
  • future MCPs News, macro, Tiingo, social, or other context providers should follow the same MCP pattern instead of being embedded into app logic.

Agent Plane

  • Claude Code Runs as the research and decision engine.
  • .claude/agents Specialized subagents such as research, skepticism, and order planning.
  • .claude/skills Reusable policy and workflow guidance.
  • .claude/commands Operator-facing project commands.

Presentation Plane

  • apps/audit-ui Research terminal for theses, session state, schedules, triggers, and execution replay.

Topology

  1. supervisor starts or resumes a Claude Code session.
  2. Claude Code loads MCP config and can call artifact-mcp, supervisor-mcp, and polymarket-mcp.
  3. Claude or operator flows write artifacts and execution records into artifact-api.
  4. audit-ui reads artifact-api and supervisor to present the current system state.
                   +----------------------+
                   |     Claude Code      |
                   |  skills / agents /   |
                   |  commands / memory   |
                   +----------+-----------+
                              |
                loads `.mcp.json` / `.mcp.docker.json`
                              |
          +-------------------+-------------------+-------------------+
          |                   |                   |                   |
          v                   v                   v                   v
+----------------------+ +----------------------+ +----------------------+ +----------------------+
|     artifact-mcp     | |    supervisor-mcp    | |   polymarket-mcp    | |     future MCPs      |
| journal tools        | | lifecycle / triggers | | Gamma / CLOB tools  | | news / Tiingo / etc. |
+----------+-----------+ +----------+-----------+ +----------+-----------+ +----------------------+
           |                          |                        |
           +-------------+------------+------------------------+
                         |
                         v
+----------------------+       +----------------------+
|      supervisor      |<----->|     artifact-api     |
| sessions / prompts / |       | artifacts / journal /|
| schedules / triggers |       | execution records    |
+----------+-----------+       +----------+-----------+
           |                               |
           +---------------+---------------+
                           |
                           v
                  +----------------------+
                  |       audit-ui       |
                  | thesis + session +   |
                  | execution terminal   |
                  +----------------------+

Environment

Copy .env.example to .env and set at minimum:

  • DATABASE_URL

Claude credentials:

  • direct Anthropic API:
    • ANTHROPIC_API_KEY
  • gateway / proxy / custom bearer auth:
    • ANTHROPIC_AUTH_TOKEN
    • ANTHROPIC_BASE_URL

Supervisor runtime:

  • CLAUDE_PERMISSION_MODE
  • CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS
  • CLAUDE_MCP_CONFIG_PATH
  • SUPERVISOR_UID
  • SUPERVISOR_GID

For Polymarket live tools:

  • POLY_DATA_API_URL: override for Data API if needed.
  • POLY_PRIVATE_KEY: L1 signer private key used to sign auth payloads and orders.
  • POLY_API_KEY, POLY_SECRET, POLY_PASSPHRASE: CLOB L2 API credentials.
  • POLY_SIGNATURE_TYPE: wallet mode for the signer. 0=EOA, 1=POLY_PROXY, 2=GNOSIS_SAFE.
  • POLY_ADDRESS: wallet / funder address used by this repo for default position queries.
  • POLY_FUNDER: set this explicitly when the funded proxy/safe address differs from the signer key.
  • POLY_ALLOW_LIVE_TRADING=true: hard switch for write tools.

Notes:

  • In proxy/safe setups, the address visible in Polymarket is usually the wallet/funder, not the raw signer.
  • This repo does not currently use Polymarket Builder / Relayer credentials. Those are separate from the CLOB user credentials above.

Local Stack

docker compose up --build

Services:

  • artifact-api on :8080
  • artifact-mcp on :8802
  • polymarket-mcp on :8801
  • supervisor on :8081
  • supervisor-mcp on :8803
  • audit-ui on :4174 by default

Docker runtime notes:

  • supervisor defaults to CLAUDE_PERMISSION_MODE=bypassPermissions
  • CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=true is expected for the dedicated containerized runtime
  • the container runs as a non-root user and persists Claude home state in the supervisor-home volume
  • if your host uid/gid is not 1000:1000, set SUPERVISOR_UID and SUPERVISOR_GID in .env before build

MCP services run as standalone HTTP MCP services:

  • local Claude Code uses .mcp.json
  • Docker supervisor uses .mcp.docker.json
  • artifact-mcp default endpoint is http://127.0.0.1:8802/mcp
  • supervisor-mcp default endpoint is http://127.0.0.1:8803/mcp
  • polymarket-mcp default endpoint is http://127.0.0.1:8801/mcp
  • polymarket-mcp current tool surface is 64 tools, including raw Gamma/Data/CLOB wrappers plus curated discovery, pricing, positions, and order-management tools

Published Images

For environments that should not build locally, use the image-based compose file:

docker compose -f docker-compose.images.yml up -d

Required env:

  • POLYAGENT_IMAGE_NAMESPACE
  • POLYAGENT_IMAGE_TAG

The image tags are intended to match the Docker Hub publish workflow in .github/workflows/docker-publish.yml.

Published image names:

  • polyagent-artifact-api
  • polyagent-artifact-mcp
  • polyagent-polymarket-mcp
  • polyagent-supervisor
  • polyagent-supervisor-mcp
  • polyagent-audit-ui

Local Development

1. Prepare env

cp .env.example .env

Fill one Claude auth mode:

  • direct Anthropic:
    • ANTHROPIC_API_KEY
  • gateway / proxy:
    • ANTHROPIC_AUTH_TOKEN
    • ANTHROPIC_BASE_URL

If you want the web UI to force a login page before entering the app, also set:

  • AUTH_ENABLED=true
  • AUTH_JWT_SECRET=<long random secret>
  • AUTH_OPERATOR_USERNAME=<operator username>
  • AUTH_OPERATOR_PASSWORD_HASH=<pbkdf2 hash>

Generate the password hash with:

cd services/supervisor
UV_CACHE_DIR=/tmp/uv-cache uv sync --locked
uv run python -c "from passlib.hash import pbkdf2_sha256; print(pbkdf2_sha256.hash('change-me'))"

Testing

Python services use pytest; the frontend uses vitest.

Run backend tests:

cd services/supervisor && uv sync --locked --dev && uv run pytest
cd services/artifact-api && uv sync --locked --dev && uv run pytest
cd services/polymarket-mcp && uv sync --locked --dev && uv run pytest

Run frontend tests:

cd apps/audit-ui
npm ci
npm run test
npm run build

GitHub Actions:

  • test.yml Runs Python tests, frontend tests, and validates both compose files.
  • docker-publish.yml Builds and pushes all runtime images to Docker Hub.

Runtime behavior:

  • when AUTH_ENABLED=true, unauthenticated users are redirected to /auth
  • POST /api/v1/auth/login returns a JWT bearer token
  • the UI stores that token in browser sessionStorage
  • supervisor and artifact-api require Authorization: Bearer <token> on protected routes

2. Run services without Docker

artifact-api

cd services/artifact-api
UV_CACHE_DIR=/tmp/uv-cache uv sync --locked
uv run uvicorn app.main:app --host 0.0.0.0 --port 8080

supervisor

cd services/supervisor
UV_CACHE_DIR=/tmp/uv-cache uv sync --locked
uv run uvicorn app.main:app --host 0.0.0.0 --port 8081

artifact-mcp

cd services/artifact-mcp
UV_CACHE_DIR=/tmp/uv-cache uv sync --locked
uv run python -m app.main

supervisor-mcp

cd services/supervisor-mcp
UV_CACHE_DIR=/tmp/uv-cache uv sync --locked
uv run python -m app.main

polymarket-mcp

cd services/polymarket-mcp
UV_CACHE_DIR=/tmp/uv-cache uv sync --locked
uv run python -m app.main

audit-ui

cd apps/audit-ui
npm install
npm run dev

Local Claude Code Debugging

Yes. For inner-loop development, local terminal debugging is the preferred path.

You do not need to go through supervisor just to test MCP wiring, prompts, skills, or .claude policy. Run Claude Code directly from the repo root so it picks up:

  • CLAUDE.md
  • .claude/agents
  • .claude/skills
  • .claude/commands
  • .mcp.json

Important: .mcp.json is now an HTTP MCP config, not a stdio autostart config. That means Claude Code will try to connect to all configured MCP endpoints; it will not start any of them for you.

Start the MCP services you want to expose first:

cd /home/bryantsuen/workspace/finance/polyagent/services/artifact-mcp
UV_CACHE_DIR=/tmp/uv-cache uv sync --locked
uv run python -m app.main

cd /home/bryantsuen/workspace/finance/polyagent/services/supervisor-mcp
UV_CACHE_DIR=/tmp/uv-cache uv sync --locked
uv run python -m app.main

cd /home/bryantsuen/workspace/finance/polyagent/services/polymarket-mcp
UV_CACHE_DIR=/tmp/uv-cache uv sync --locked
uv run python -m app.main

Interactive debugging:

cd /home/bryantsuen/workspace/finance/polyagent
claude --mcp-config .mcp.json --add-dir /home/bryantsuen/workspace/finance/polyagent

Non-interactive prompt test:

cd /home/bryantsuen/workspace/finance/polyagent
claude -p "Search Polymarket markets about Fed cuts and summarize the top candidates." \
  --mcp-config .mcp.json \
  --add-dir /home/bryantsuen/workspace/finance/polyagent \
  --setting-sources project,local \
  --permission-mode dontAsk

Useful local debug targets:

  • MCP wiring: ask Claude to call list_artifacts, list_managed_sessions, or search_markets
  • policy wiring: run project commands in .claude/commands
  • subagent wiring: ask Claude to delegate to one of the project agents
  • supervisor parity: compare local claude -p ... --session-id ... behavior with supervisor

Use supervisor when you want:

  • persistent managed sessions
  • HTTP prompt dispatch
  • schedules
  • trigger metadata
  • audit UI integration

About

Native claude code for polymarket

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages