Autonomous AI agent with Marathon Mode — multi-day task execution powered by Gemini 3 with Thinking Levels & Thought Signatures, multi-agent orchestration, 27+ integrations
npm install wispy-ai
Autonomous AI Agent Infrastructure — Think for Days, Pay for Services, Prove Identity On-Chain
Website ·
API Docs ·
npm ·
Issues ·
Quickstart
bash
npm install -g wispy-ai
`
Other installation methods
pnpm:
`bash
pnpm add -g wispy-ai
`
Homebrew (macOS/Linux):
`bash
brew tap brn-mwai/wispy && brew install wispy
`
Shell script (macOS/Linux):
`bash
curl -fsSL https://wispy.cc/install.sh | bash
`
PowerShell (Windows):
`powershell
irm https://wispy.cc/install.ps1 | iex
`
CMD (Windows):
`cmd
curl -o install.bat https://wispy.cc/install.bat && install.bat
`
$3
`bash
wispy setup
`
This interactive wizard will configure your AI credentials (Gemini API key or Vertex AI), channels, and optional blockchain integrations.
$3
`bash
Interactive chat
wispy chat
Start the full gateway (API + channels + A2A)
wispy gateway
Run a marathon (multi-day autonomous task)
wispy marathon "Build a full-stack SaaS dashboard with Next.js"
Execute a single agent task
wispy agent "Research the DePIN market and produce a detailed report"
`
---
Features
$3
Wispy's Marathon Mode plans complex tasks into milestones, then executes them autonomously over hours or days. It checkpoints progress, self-recovers from failures, and sends real-time updates via Telegram or WhatsApp.
`bash
wispy marathon "Build and deploy a REST API with auth, tests, and docs"
`
- Deep planning with Gemini 2.5 Pro (up to 24K token thinking budget)
- Autonomous milestone-by-milestone execution
- Self-recovery — analyzes failures and retries with different approaches
- Checkpointing — pause anytime, resume exactly where you left off
- Real-time notifications on progress via Telegram/WhatsApp
$3
Wispy handles HTTP 402 Payment Required responses automatically. When it encounters a premium API, it checks spending limits, requests approval through the Trust Controller, and pays with USDC on Base.
- Automatic HTTP 402 handling with USDC on Base network
- Configurable spending limits per task
- Trust Controller approval workflows
- Full transaction logging and audit trail
$3
Register your agent on-chain using the ERC-8004 standard. This gives Wispy a verifiable, decentralized identity that other agents and services can trust.
- On-chain registration on Base Sepolia
- Reputation tracking system
- Serves /.well-known/agent.json for discovery
- Validation framework for trust verification
$3
Wispy implements Google's Agent-to-Agent protocol for discovering, delegating tasks to, and receiving results from other AI agents.
- Agent card publishing and discovery
- Task delegation with structured messaging
- Secure Ed25519 message signing
- Compatible with the broader A2A ecosystem
$3
| Category | Tools |
|----------|-------|
| Code | File operations, shell execution, project scaffolding |
| Web | HTTP requests, web scraping, browser automation (Playwright) |
| Data | PDF/DOCX/Excel generation, CSV parsing, chart creation |
| Media | Image generation (Imagen 3), image editing, voice TTS |
| Blockchain | Wallet management, contract interaction, ENS resolution |
| Memory | Vector embeddings, semantic search, conversation history |
| System | Cron scheduling, reminders, MCP server integration |
$3
| Channel | Description |
|---------|-------------|
| CLI | Interactive REPL with rich formatting and voice mode |
| Telegram | Full bot with inline responses and thinking indicators |
| WhatsApp | Business API integration with media support |
| REST API | Public API with key management for third-party integrations |
| WebSocket | Real-time streaming for web applications |
| A2A | Agent-to-agent protocol server on port 4002 |
$3
Wispy exposes a full REST API so you can integrate it into your own products. Manage API keys, set scopes and rate limits, and interact with all Wispy features programmatically.
`bash
Create an API key
wispy api create "My App" --scopes chat,marathon
Use it
curl -H "Authorization: Bearer wsk_..." https://your-wispy-instance/api/v1/chat \
-d '{"message": "Hello"}'
`
See the full API documentation at wispy.cc/developers.
---
Architecture
`
┌────────────────────────────────────────────────────────────────────┐
│ WISPY PLATFORM │
├────────────────────────────────────────────────────────────────────┤
│ │
│ Channels Core Engine Protocols │
│ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ CLI │ │ Gemini 2.5 │ │ x402 │ │
│ │ Telegram │────▶│ Pro Agent │────▶│ Payments │ │
│ │ WhatsApp │ │ + Marathon │ │ (USDC/Base) │ │
│ │ REST API │ │ Mode │ ├──────────────┤ │
│ │ WebSocket│ └──────┬───────┘ │ ERC-8004 │ │
│ └──────────┘ │ │ Identity │ │
│ │ ├──────────────┤ │
│ Services │ │ A2A Protocol │ │
│ ┌──────────┐ ┌──────▼───────┐ │ (Google) │ │
│ │ Memory │ │ 27+ Tools │ └──────────────┘ │
│ │ Cron │ │ + MCP │ │
│ │ Skills │ │ Servers │ Security │
│ │ Browser │ └──────────────┘ ┌──────────────┐ │
│ │ Voice │ │ Trust Ctrl │ │
│ └──────────┘ │ Device Auth │ │
│ │ Rate Limits │ │
│ └──────────────┘ │
└────────────────────────────────────────────────────────────────────┘
`
---
Configuration
$3
`env
GEMINI_API_KEY=your-api-key
`
Get your key at Google AI Studio.
$3
`env
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1
`
Then authenticate:
`bash
gcloud auth application-default login
`
$3
Wispy uses ~/.wispy/config.yaml:
`yaml
agent:
name: Wispy
id: wispy-agent-001
gemini:
vertexai:
enabled: true
project: your-gcp-project
location: us-central1
models:
pro: gemini-2.5-pro
flash: gemini-2.5-flash
image: imagen-3.0-generate-002
embedding: text-embedding-004
marathon:
thinkingLevel: ultra # Thinking budget: low | medium | high | ultra
checkpointInterval: 5
wallet:
enabled: true
chain: base-sepolia
channels:
telegram:
enabled: true
whatsapp:
enabled: true
rest:
enabled: true
port: 4001
web:
port: 4000
security:
autonomousMode: false # Auto-approve file/code operations
actionGuard:
enabled: true
memory:
heartbeatIntervalMinutes: 30
`
---
Security
Wispy is built with security as a first-class concern:
- Device Identity — Ed25519 keypair generated per device for authentication
- Encrypted Storage — AES-256-GCM encryption for credentials and sensitive data
- Trust Controller — Approval workflows for sensitive operations (file writes, payments, shell commands)
- Action Guard — Configurable rules for what the agent can and cannot do autonomously
- API Key System — Scoped keys with rate limiting, expiry, and usage tracking
- Secret Scanner — Automatic detection and redaction of API keys in outputs
- Loop Detection — Prevents infinite tool execution loops
- Session Isolation — Separate contexts for different users and channels
---
CLI Reference
`
wispy chat Interactive chat session
wispy gateway Start full gateway (API + channels + A2A)
wispy marathon Start autonomous multi-day task execution
wispy agent Execute a single agent task
wispy setup Interactive configuration wizard
wispy doctor Diagnose configuration issues
wispy skill Run a specific skill
wispy api create Create an API key
wispy api list List API keys
wispy api revoke Revoke an API key
wispy voice Enter voice mode
wispy history View conversation history
`
---
Technical Specs
| Component | Details |
|-----------|---------|
| AI Engine | Google Gemini 2.5 Pro / Flash via Vertex AI or API key |
| Thinking Budget | 128 — 24,576 tokens (configurable) |
| Runtime | Node.js 20+, TypeScript 5.7, ESM |
| Blockchain | Base Sepolia (chainId: 84532) |
| Payments | USDC via x402 protocol (Coinbase CDP) |
| Identity | ERC-8004 on-chain agent registration |
| Agent Comms | A2A Protocol (Google) |
| Tools | 27+ built-in + MCP server support |
| Channels | CLI, Telegram, WhatsApp, REST API, WebSocket, A2A |
| Memory | SQLite + vector embeddings (text-embedding-004) |
| Browser | Playwright-based headless automation |
---
API Usage
$3
`typescript
import { Agent } from 'wispy-ai';
const agent = new Agent({ config, runtimeDir, soulDir });
for await (const chunk of agent.chatStream("Build a landing page", "user-1", "api")) {
process.stdout.write(chunk.content);
}
`
$3
`typescript
const marathon = agent.startMarathon("Build a full-stack app with auth and tests");
marathon.on('milestone', (m) => console.log(Completed: ${m.name}));
marathon.on('complete', (result) => console.log('Done!', result));
`
$3
`bash
Create API key
wispy api create "My Integration" --scopes chat,chat:stream,marathon
Chat
curl -X POST https://localhost:4001/api/v1/chat \
-H "Authorization: Bearer wsk_..." \
-H "Content-Type: application/json" \
-d '{"message": "Hello, Wispy"}'
Stream (SSE)
curl -N https://localhost:4001/api/v1/chat/stream \
-H "Authorization: Bearer wsk_..." \
-H "Content-Type: application/json" \
-d '{"message": "Explain quantum computing"}'
`
Full API docs: wispy.cc/developers
---
Deployed Contracts
| Contract | Address | Network |
|----------|---------|---------|
| Agent Registry | 0x158B236CC840FD3039a3Cf5D72AEfBF2550045C7 | Base Sepolia |
---
Contributing
Contributions are welcome! Please open an issue or pull request on GitHub.
`bash
git clone https://github.com/brn-mwai/wispy.git
cd wispy
npm install
npm run build
npm run dev
``
Wispy is built by Hausor Labs Team (HL Team)