Send events. Watch your city react.

Quickstart

Send a single event. Get back a simulation of what it would do to your city — earnings, state transitions, webhook payloads. No real data is written until you swap /sandbox/events for the production endpoint.

1. Send your first event

curl -X POST https://stashville.app/api/sandbox/events \
  -H "Content-Type: application/json" \
  -d '{
    "type": "coding_started",
    "project": "my-app",
    "language": "typescript"
  }'

2. Understand the response

{
  "simulated_effects": [
    { "id": "effect_1", "type": "agent_spawn", "description": "Agent walks to building" }
  ],
  "earnings_preview": {
    "base_amount": 10,
    "multiplier": 1.2,
    "total": 12,
    "breakdown": "TypeScript: 1.2x multiplier"
  },
  "state_preview": { "from": "STEADY", "to": "THRIVING" },
  "webhook_payloads": [...]
}

3. Language multipliers

Events carrying a language field get a coin multiplier. This rewards harder-to-write languages — a commit in Rust is worth more than the same commit in JavaScript.

Daemon Setup

The Stashville daemon is a local background service that tracks your coding activity and syncs it with your city. It monitors git commits, integrates with Claude Code, and works offline.

1. Install the daemon

curl -fsSL https://stashville.city/install.sh | sh

This downloads the appropriate binary for your system (macOS, Linux, Windows) and installs it to ~/.local/bin.

2. Authenticate

stashville login

Opens your browser to sign in with your Stashville account. For headless environments (SSH, CI), the daemon falls back to device code flow.

3. Run setup

stashville setup

Scans your default directories for git repositories, installs Claude Code hooks, and registers the daemon to start on login (macOS).

4. Start the daemon

stashville

Runs the daemon in the foreground. On macOS, the daemon starts automatically on login after running setup.

Available commands

Configuration

The daemon stores config in ~/.stashville/config.yaml. Override settings with environment variables:

Troubleshooting

Daemon won't start: Another instance may be running. Check ~/.stashville/daemon.pid and kill the process.

Not authenticated: Run stashville logout then stashville login.

Hooks not working: Run stashville status to check, then stashville setup to reinstall.

Debug mode: Run stashville --debug for detailed logging including raw hook payloads.

Event Types

Events are the language Stashville speaks. Each one triggers specific effects in the city — a GIT_COMMIT rings the bell, a FILE_CHANGE spawns an agent, anIDLE_START sends workers home.

Common Fields

Endpoints

All endpoints accept and return JSON unless marked otherwise. Base URL: https://stashville.app in production,http://localhost:3745 in local dev.

Content-Type: application/json

{ "type": "coding_started", "project": "my-app", "language": "typescript" }

{ "simulated_effects": [...], "earnings_preview": {...}, "webhook_payloads": [...] }

{ "type": "FILE_CHANGE", "project": "my-app" }

{ "valid": true, "event": {...} }

{ "scenarios": [{ "id": "quick-session", "name": "Quick Coding Session", ... }] }

{ "scenario_id": "quick-session" }

{ "scenario": {...}, "results": [...], "summary": {...} }

Accept: text/event-stream

scenario=active-coding | idle | multiplayer

Code Examples

Copy-paste to get going. These call the sandbox endpoints — no account needed to experiment. Once you're ready, swap/api/sandbox/* for the production routes.

curl -X POST https://stashville.app/api/sandbox/events \
  -H "Content-Type: application/json" \
  -d '{
    "type": "GIT_COMMIT",
    "project": "my-app",
    "language": "typescript",
    "metadata": {
      "message": "feat: add new feature",
      "sha": "abc123"
    }
  }'

curl -X POST https://stashville.app/api/sandbox/events \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "type": "coding_started", "project": "api", "language": "go" },
      { "type": "FILE_CHANGE", "project": "api" },
      { "type": "GIT_COMMIT", "project": "api", "metadata": { "message": "fix: bug" } },
      { "type": "coding_stopped", "project": "api" }
    ]
  }'

const response = await fetch("/api/sandbox/events", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    type: "coding_started",
    project: "my-app",
    language: "rust",
  }),
});

const result = await response.json();
console.log("Effects:", result.simulated_effects);
console.log("Earnings:", result.earnings_preview);

const eventSource = new EventSource(
  "/api/sandbox/stream?scenario=active-coding"
);

eventSource.addEventListener("city_event", (e) => {
  const data = JSON.parse(e.data);
  console.log("City event:", data);
});

eventSource.addEventListener("earnings", (e) => {
  const data = JSON.parse(e.data);
  console.log("Earnings:", data);
});

eventSource.addEventListener("stream_end", () => {
  eventSource.close();
});

// List available scenarios
const list = await fetch("/api/sandbox/scenarios").then(r => r.json());
console.log(list.scenarios);

// Run a scenario
const result = await fetch("/api/sandbox/scenarios", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ scenario_id: "full-day-session" }),
}).then(r => r.json());

console.log("Total effects:", result.summary.total_effects);
console.log("State transitions:", result.summary.state_transitions);

Rate Limits

Sandbox

The sandbox API is rate limited to 60 requests/minute per IP. Check the X-RateLimit-Remaining header for your current quota.

Bursts of events from a CI job are fine. If you're about to send more than 60 in a minute, buffer and send a batch using the{ events: [...] } shape — one request, many events.

Production

A well-behaved client that honors Retry-After effectively cannot reach the ban threshold. If your client is producing bursts (e.g. git history backfill), pace the emissions instead of sending them all at once.

Production Integration

Ready to send real events? The sandbox sections above cover the event shape and wire format — this section is about the rules your client has to follow to operate indefinitely without being rate-limited or banned.

Getting an API key

Two flows, depending on what you're building. Both mint the same sv_full_* / sv_write_* keys. Send every request with Authorization: Bearer sv_... — requests without a valid bearer token return 401 UNAUTHORIZED.

Manual key — for your own integration

Use this when the integration authenticates as you — a personal CI hook, a private bot, your own daemon. Sign in, visit /settings/integrations, create an integration, and pick a scope:

• write — can send events, cannot read state
• full — can send events, read state, and open streaming connections

Device code flow — for integrations that authenticate users

Use this when third-party users will install or sign into your integration — a VS Code extension, a Slack bot, a CLI tool, another developer-facing service. RFC 8628-compatible. The Stashville daemon uses this same flow; any integration can.

1. Start: POST /api/auth/daemon/device-code with body { hostname: "My Integration" }. Response includes device_code, user_code (like ABCD-1234), verification_url, and interval.
2. Show the user the verification URL and the user code. They visit the URL, sign in if needed, and enter the code to approve.
3. Poll GET /api/auth/daemon/device-code/poll?device_code=... every interval seconds. Status transitions pending → authorized (returns api_key, user_email, and integration_id) or denied / expired. Save the integration_id — you'll need it when you open the SSE stream.
4. Back off on 429. If you poll too fast, the server returns 429 with error slow_down — add the returned interval seconds to your poll cadence.

The user_code expires after 5 minutes. Default poll interval is 5 seconds.

GET /api/integrations/me

Returns the current integration and user context for any valid bearer token. Use it to:

• Look up your own integration_id if your key didn't come from the device-code flow (e.g., a key the user pasted from the UI). Needed for POST /api/integrations/{id}/stream-token.
• Verify a key on client startup — 200 means valid + active; 401 means invalid or revoked.

GET /api/integrations/me
Authorization: Bearer sv_full_...

{
  "data": {
    "authMethod": "bearer",
    "integration": { "id": "...", "name": "...", "scope": "FULL", "status": "ACTIVE", "keyPrefix": "sv_full_a1b2****" },
    "user": { "id": "...", "email": "you@example.com", "name": "Your Name" }
  }
}

Earning rules

Events mint in-game coins, subject to anti-gaming caps. Flooding the API does not inflate earnings — cooldown and diminishing returns apply well before the throughput cap.

• 500 coins/day per user. Diminishing returns from 300 (half-rate) and 400 (quarter-rate).
• 10-second cooldown per projectId:eventType: same-type events inside the window earn zero.
• 7-day timestamp bound: events older than this are rejected with BAD_REQUEST. Drop them from your client queue.
• 100 coins/day separate sub-cap for CUSTOM events.

Error codes

Recipe: daemon-independent integration

The Stashville daemon is optional. Stashville is a platform; the daemon is one client of many. Third-party integrations (VS Code extensions, tiling window managers like Perch, CI bots, custom CLIs) can own the entire flow end-to-end via the public API without installing or running the daemon on the user's machine.

A third-party integration that manages its own worktrees and sends events directly, without requiring the Stashville daemon to be installed on the user's machine.

1. Authenticate the user via device code flow. POST /api/auth/daemon/device-code then GET /api/auth/daemon/device-code/poll
   Why: Gets a user-approved API key without the user having to create one manually. The authorized response returns both `api_key` AND `integration_id` — save both; you'll need integration_id for the SSE stream-token step.
2. Verify the key / look up integration_id if you don't have it. GET /api/integrations/me
   Why: Optional but recommended on client startup. Returns the current integration (id, name, scope, status) and user (id, email, name). A 200 response means the key is valid; 401 means it's not. If your key came from somewhere other than the device-code flow (e.g., a key the user pasted in from the UI), this is how you look up integration_id for the stream-token call.
3. Check whether a worktree path is already a known project. GET /api/projects?path={absolute-path}
   Why: When the user opens a tile for a repo, look up the project in one call. 0 results = new repo; 1 result = existing project.
4. Create a project if needed. POST /api/projects
   Why: Upsert-by-path semantics on the server — safe to call with the same path twice. Returns the existing project if one already exists at that path; creates otherwise.
5. Register the worktree. POST /api/worktrees
   Why: Upsert-by-path. Associates the worktree with a project and stores branch/commit state. Idempotent — calling again on a path update branches/commits without duplicating rows. This replaces the daemon's WORKTREE_SCAN flow entirely.
6. Send activity events as they happen. POST /api/events
   Why: Real-time signals (GIT_COMMIT, TOOL_USAGE, SESSION_START, etc.) that drive state transitions and coin earnings. Batch multiple events per request to stay under the 100/min burst cap.
7. Subscribe to real-time project state. GET /api/city-state/stream?token=st_... (after POST /api/integrations/{id}/stream-token)
   Why: SSE stream of project state changes — ideal for keeping a tile UI live without polling. Requires a short-lived stream token issued from your FULL-scope API key.
8. Read state on demand (fallback or first render). GET /api/projects/{id} or GET /api/projects
   Why: Single-project fetch for a specific tile, or the full catalog to populate a project picker UI.

Real-time state updates (SSE)

For live tiles, dashboards, or overlays: subscribe to Server-Sent Events at GET /api/city-state/stream?token={streamToken} instead of polling /api/state. One open connection, no rate-limit cost on idle ticks, full fan-out to every client of every project the user owns. Full details in the Real-time Updates section below.

Building an integration with an LLM

Point your agent at /llms-full.txt. That file is a plain-text reference of every event type, every required/optional field, every error code, and every rule — rendered from the same source as this page, so numbers can never drift. Hand it to Claude (or Cursor, Copilot, etc.) with “build me a Stashville integration” and it should produce a compliant client in one shot.

There is also /llms.txt at the site root — a short index for LLM crawlers that points to /llms-full.txt.

Real-time Updates (SSE)

Integrations that render live UI — tiles, dashboards, overlays — should subscribe to Stashville's Server-Sent Events stream instead of polling/api/state. One open connection delivers project-state changes within milliseconds and costs zero rate-limit budget on idle ticks.

Why a stream token (not the API key)?

API keys must never appear in URLs — they leak via access logs, browser history, and the Referer header. The SSE handshake uses the EventSource API which only supports GET + query strings, so integrations first exchange their API key for a short-lived stream token.

Issue a stream token

POST /api/integrations/{integrationId}/stream-token (requires FULL scope) returns:

{
  "data": {
    "streamToken": "st_...",
    "expiresAt": "ISO 8601 timestamp, 5 minutes from now"
  }
}

Tokens expire after 5 minutes. Rotate before expiry (see the auth_expired event below).

Connect

const es = new EventSource(
  "https://stashville.vercel.app/api/city-state/stream?token=" + streamToken
);

es.addEventListener("update", (ev) => {
  const projects = JSON.parse(ev.data); // array of project snapshots
  // apply to your UI
});

es.addEventListener("auth_expired", async () => {
  const newToken = await fetchStreamToken();
  es.close();
  // reconnect with newToken...
});

es.addEventListener("state.reset", (ev) => {
  const fullSnapshot = JSON.parse(ev.data);
  // replace local state — don't merge with stale deltas
});

Events on the stream

Reconnection with Last-Event-ID

Every update event carries an id: field. When your connection drops, EventSource automatically reconnects and sends the last seen id in the Last-Event-ID header. Stashville buffers events for 120 seconds — reconnects within that window receive missed events seamlessly.

Reconnect gaps longer than 2 minutes receive a state.reset event containing a full snapshot. Replace your local state from it; do not attempt to merge stale deltas.

Keepalive

The server sends a ping event every 30 seconds to keep intermediary proxies from closing idle connections. No action required. Absence of pings for > 2× the interval indicates a dead connection — reconnect.

Integration Checklist

Self-audit list for integration authors. Tick every applicable box and your integration is a first-class Stashville citizen — correct, safe, and polished. Items marked (optional) only apply if your client uses SSE. Every item includes a Why so edge cases are judgment calls, not guesswork.

Claude Code Hooks

Complete reference of every hook Claude Code exposes. The Used column shows whether the Stashville daemon currently listens for it; Event shows what Stashville event each hook produces. Useful if you're building a similar integration on top of Claude Code, or extending the Stashville daemon to listen for more signals. Upstream reference: docs.claude.com/claude-code/hooks.