Documentation
Getting started
Everything you need to run the SS-1 Signal Shell demo locally. The demo uses a fully mocked intelligence pipeline — no API keys required to run.
Prerequisites
SS-1 is a macOS desktop app backed by a Python sidecar. To run the demo you need:
The demo can also run as a browser app (React + Vite dev server) without the Tauri desktop shell. This is the recommended path for quick evaluation.
Setup
Clone and install dependencies for both the sidecar and the React app:
# 1. Install Python sidecar dependencies
cd python_app
uv sync
# 2. Install React app dependencies
cd ../ss1-app
npm install
# 3. Copy env file (no keys required for demo)
cd ../python_app
cp .env.example .env
No API keys are required to run the mock demo. The ANTHROPIC_API_KEY field can be left empty for the demo mode.
Running the demo
Start the Python sidecar first, then the React dev server. Both must be running.
Terminal 1 — Python sidecar
cd python_app
uv run uvicorn main:app --reload --port 8001
Sidecar runs at localhost:8001
Terminal 2 — React dev server
cd ss1-app
npm run dev
App opens at localhost:5174
Open http://localhost:5174 in your browser. The SS-1 terminal interface will load.
Commands
| Command | Shortcut | What it does |
|---|---|---|
| ss1 init "Name" | — | Create a new project and generate manifest.md |
| ss1 sync | ⌘⇧S | Trigger on-demand market scan across all tracked URLs |
| ss1 history | ⌘H | View manifest version timeline with git commits |
| ss1 export --latest | ⌘E | Export most recent approved brief to Markdown |
| ss1 status | — | Show current project status and signal count |
| ss1 manifest edit | ⌘M | Open manifest in editable panel |
Demo workflow
The recommended demo sequence to show the full SS-1 loop:
ss1 init "Meridian Analytics"
Creates the demo project with a pre-populated manifest.
ss1 sync
Runs the mock scan pipeline. Watch the log stream as each URL is checked and scored.
Review the SignalBriefCard
Read the intelligence brief, strategic implication, and proposed manifest diff. Click UPDATE MANIFEST to approve.
Review the ManifestDiffCard
The diff shows exactly what changed in the manifest. A git commit has been created.
ss1 history
The timeline shows both versions — the initial manifest and the agent-triggered update.
ss1 export --latest
The ExportReadyCard shows the brief has been saved as a Markdown file.
Key concepts
Project Manifest
A local markdown file under git version control. The SSOT for everything the intelligence pipeline reasons against: vision, priorities, competitors, archetypes.
Signal
A detected change in the external competitive landscape. Assigned a significance score (0–100) by the Significance Gate agent.
Intelligence Brief
A structured Sonnet-generated output: what changed, strategic implication, proposed manifest update, and strategic response options. Not a news summary.
HITL Gate
Human-In-The-Loop approval gate. Every agent-proposed manifest write must pass through a diff preview and explicit user approval before the file is touched.
ActionCard
The standard JSON payload for all agent outputs. card_id, type, severity, content, and actions. Card state is owned by the backend; the frontend only renders.
Significance Gate
A Haiku-powered node that scores each detected delta 0–100. Signals below 40 are discarded silently. Above 40, a brief is generated.
Manifest History
A timeline of git commits to manifest.md. Each entry records the commit hash, timestamp, change summary, and whether it was triggered by the agent or the user.
Sidecar
The Python FastAPI process that runs alongside the Tauri desktop app. Owns all business logic. The frontend communicates via WebSocket (streaming) and HTTP (discrete actions).
Guardrails
SS-1 applies the following constraints to every session:
- ·No manifest write without explicit HITL approval. Agent proposals are previewed as diffs.
- ·Scan loops are capped at 10 iterations per session. A SCAN_STATUS card halts the pipeline if the limit is reached.
- ·All OSINT calls (Firecrawl/Tavily) respect rate limits with exponential backoff. Silent failure is not acceptable.
- ·Git operations use GitPython exclusively — never shell out to git directly.
- ·Dry-run is implicit: the Propose Node generates a diff preview before any write is submitted to the approval gate.
Troubleshooting
WebSocket shows 'Offline' in the status bar
The Python sidecar is not running. Start it with: cd python_app && uv run uvicorn main:app --port 8001
npm run dev fails with module not found
Run npm install in the ss1-app/ directory. Node 18+ is required.
uv sync fails
Ensure uv is installed (brew install uv) and Python 3.11+ is available. Run: uv python install 3.11
Commands have no effect
Both the sidecar (port 8001) and the React dev server (port 5174) must be running. Check the browser console for HTTP errors.