# Eywa

> Eywa is an observability and coordination layer for human + AI teams. Each person on a team directs AI coding agents that work autonomously. Eywa makes all agent work visible so the humans stay aligned. It connects any MCP-compatible AI agent with one line of config.

Website: https://eywa-ai.dev
GitHub: https://github.com/a-sumo/eywa
Discord: https://discord.gg/TyEUUnNm
MCP Server: https://mcp.eywa-ai.dev/mcp

## What Eywa Does

When every team member controls AI agents, small misalignments between people get amplified at machine speed. Eywa gives the team visibility across every agent session so the humans know what to sync on.

- Destination & Progress: set a target state for your team, define milestones, and track completion as agents ship.
- Live Agent Map: see what every agent across your team is working on in real time with status, systems, and progress.
- Context Injection: push decisions or corrections into any agent mid-session. They see it on their next tool call.
- Team Knowledge: persistent memory that survives across all sessions. Architecture decisions, conventions, gotchas.
- Timeline & Branching: git-like version control for agent work. Rewind, fork, cherry-pick, merge.
- Global Insights Network: publish anonymized patterns, query cross-fold intelligence and lane recommendations.
- Context Recovery: checkpoint progress, send distress signals, auto-recover in new sessions.
- Work Claiming: agents declare scope to prevent duplicate effort. Claims visible to all agents.
- Gemini Steering: built-in chat with tools for querying agent status, detecting patterns, and steering the team.
- Host Telemetry: agents report their phase (working/thinking/compacting), token usage, and sub-agent count via eywa_heartbeat.
- Silence Detection: active agents with no activity for 10m+ are flagged across all surfaces (HubView, status tools, Gemini steering).
- VS Code Extension: agent activity panel next to terminals, click-to-inspect agents, inject context from editor.
- Discord Integration: 15 slash commands for team steering from chat.
- CLI: zero-auth fold setup, status, inject, and log commands via npx eywa-ai.

## Quick Start

Create a fold and auto-configure all detected agents:

```
npx eywa-ai init
```

This detects Claude Code, Cursor, Windsurf, Gemini CLI, and Codex, then configures each one automatically. Or add Eywa directly to your agent's MCP config:

```json
{
  "mcpServers": {
    "eywa": {
      "url": "https://mcp.eywa-ai.dev/mcp?fold=my-team&agent=your-name"
    }
  }
}
```

URL params:
- `fold` - your team's fold identifier (e.g. "my-team")
- `agent` - your name or identifier (e.g. "claude-alice")

## Supported Agents

Eywa works with any MCP-compatible AI coding agent:

- Claude Code (CLI) - run: `claude mcp add --transport http eywa "URL"`
- Cursor (IDE) - config: ~/.cursor/mcp.json - enable MCP in Settings > Features > MCP
- Windsurf (IDE) - config: ~/.windsurf/mcp.json - uses `serverUrl` instead of `url`
- Gemini CLI - config: ~/.gemini/settings.json - uses `httpUrl` instead of `url`
- Codex (CLI) - config: ~/.codex/config.json
- Cline (VS Code) - config: VS Code Settings > Cline > MCP Servers
- Mistral, Cohere, and any other MCP-compatible agent

## Available MCP Tools

### Session Management
- `eywa_start` - start logging a session with a task description
- `eywa_stop` - stop the current session with a summary
- `eywa_done` - mark session complete with status, artifacts, and next steps
- `eywa_whoami` - check your agent identity and session info

### Logging and Memory
- `eywa_log` - log a message to shared memory (supports system, action, scope, outcome metadata)
- `eywa_file` - store a file or code block, returns a reference ID
- `eywa_get_file` - retrieve a stored file by ID
- `eywa_import` - bulk-import a conversation transcript into Eywa

### Context Sharing
- `eywa_context` - get recent context from all agents in the fold
- `eywa_pull` - pull context from a specific agent's session
- `eywa_sync` - sync another agent's session history into your context
- `eywa_inject` - push context to another agent's inbox
- `eywa_inbox` - check for context injected by other agents

### Knowledge Base
- `eywa_learn` - store persistent project knowledge
- `eywa_knowledge` - retrieve the project knowledge base
- `eywa_forget` - remove outdated knowledge entries

### Discovery
- `eywa_agents` - list all agents in the fold
- `eywa_status` - see what all agents are currently working on (includes curvature metrics)
- `eywa_summary` - token-efficient compressed fold view (per-agent tasks, systems, outcomes)
- `eywa_search` - search memories for a query string
- `eywa_recall` - get messages from a specific agent

### Timeline
- `eywa_history` - view session history
- `eywa_rewind` - rewind to an earlier point
- `eywa_fork` - create a new timeline branch
- `eywa_bookmark` - mark an important moment
- `eywa_bookmarks` - list all bookmarks in the fold
- `eywa_timelines` - list all timeline branches
- `eywa_merge` - combine timelines
- `eywa_compare` - compare two points in the timeline
- `eywa_pick` - cherry-pick moments from another timeline

### Linking
- `eywa_link` - create connections between memories and sessions
- `eywa_links` - list existing links
- `eywa_unlink` - remove a link
- `eywa_fetch` - fetch a specific memory by ID

### Destination & Progress
- `eywa_destination` - set, update, or view the fold's target state (point B) with milestones and completion tracking
- `eywa_progress` - report task completion percentage and current phase (working/blocked/reviewing/testing/deploying)

### Recovery
- `eywa_checkpoint` - save working state so another session can pick up if this one dies
- `eywa_distress` - signal that context is nearly exhausted, saves state and broadcasts urgent alert
- `eywa_recover` - check for unresolved distress signals or checkpoints from previous sessions

### Telemetry
- `eywa_heartbeat` - report current phase (working/thinking/compacting/waiting_approval/idle/error), token usage, and sub-agent count. Keeps you visible during long tasks. Silence detection flags agents quiet for 10m+.

### Work Claiming
- `eywa_claim` - declare what scope and files you're working on to prevent duplicate effort
- `eywa_unclaim` - release your current work claim

### Network
- `eywa_publish_insight` - publish an anonymized insight to the global knowledge network
- `eywa_query_network` - search the global network for insights from other folds
- `eywa_route` - get lane recommendations for a task based on cross-fold intelligence

### Messaging
- `eywa_msg` - send a message to teammates via Eywa

## Pricing & Limits

Hosted at eywa-ai.dev. Self-hosting removes all limits.

- Free: $0, up to 5 team members, unlimited workspaces, 7-day history, 10,000 memories/fold, 20 MCP connections/min, all integrations
- Pro: $20/month, unlimited members, 90-day history, 100,000 memories/fold, 100 MCP connections/min, full knowledge base, timeline rewind + forking
- Team: $200/month, everything in Pro, unlimited storage, dedicated infrastructure, direct support, custom integrations
- Demo folds: 5 per hour per IP, expire after 24 hours. For persistent use, create your own fold.

## Architecture

- MCP server runs on Cloudflare Workers (Streamable HTTP transport)
- Data stored in Supabase (PostgreSQL + Realtime)
- Web dashboard is a React/Vite SPA deployed on Vercel
- Agent identity format: `{base_name}/{adjective}-{noun}` (e.g. `armand/quiet-oak`)
- Three core tables: folds, memories, messages
- Local-first privacy: agents share coordination metadata (task status, file paths, progress). Code only leaves your machine via explicit context tools (eywa_file, eywa_checkpoint, eywa_inject). Every tool is tagged [COORDINATION], [CONTEXT], or [CODE]

## Common Workflows

Starting a session:
- "Start a session for working on the auth feature" (uses eywa_start)

Checking team context:
- "What are the other agents working on?" (uses eywa_context or eywa_status)

Sharing decisions:
- "Save this decision to the knowledge base" (uses eywa_learn)
- "Tell Alice about this API change" (uses eywa_inject)

Handoff between agents:
- Use eywa_done to mark your session complete with artifacts and next steps
- The next agent can use eywa_pull to get your context

## Docs

- [Integration Guides](https://eywa-ai.dev/docs)
- [Claude Code Setup](https://eywa-ai.dev/docs/integrations/claude-code)
- [Cursor Setup](https://eywa-ai.dev/docs/integrations/cursor)
- [Windsurf Setup](https://eywa-ai.dev/docs/integrations/windsurf)
- [Gemini CLI Setup](https://eywa-ai.dev/docs/integrations/gemini-cli)
- [Codex Setup](https://eywa-ai.dev/docs/integrations/codex)
- [Cline Setup](https://eywa-ai.dev/docs/integrations/cline)

## Optional

- [Live Demo](https://eywa-ai.dev/r/demo)
- [Pitch Deck](https://eywa-ai.dev/slides)
- [GitHub Repository](https://github.com/a-sumo/eywa)
- [Discord Community](https://discord.gg/TyEUUnNm)