{"id":"3c5c4aab-7706-49a1-845a-ddbd64eca8ba","slug":"shuruheel-volition","kind":"skill","name":"volition","summary":"AI agent orchestration built around an activity feed rather than a chat thread","owner":"shuruheel","repoUrl":"https://github.com/shuruheel/volition","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"skill","createdAt":"2025-10-03T07:02:10.000Z","addedAt":"2026-10-21T22:08:59.484Z","logoUrl":"https://avatars.githubusercontent.com/u/2854661?u=c1478ea8523d2e75bbd9434cc9144a7c0d773cbb&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["communication"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T21:33:05.424Z","sample":false,"url":"https://conduits.dev/tools/shuruheel-volition","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Volition\n\nAn open-source AI agent orchestration platform. Your personal AI assistant that researches, emails, schedules, and takes action on your behalf — with human-in-the-loop approval for every sensitive action.\n\nBuilt with Next.js 16, Neon Postgres, and multi-provider LLM support (OpenAI + Anthropic).\n\n## Why Volition\n\nMost agent frameworks focus on chain-of-thought execution but ignore the hard parts: **durability** (what happens when a step fails?), **human oversight** (should the agent really send that email?), and **memory** (does the agent remember what it researched yesterday?).\n\nVolition solves all three with a visual, web-native platform that non-engineers can use:\n\n- **Single Agent Per User** — Sign up and your personal AI agent is auto-created. No setup friction — just enable and go. Agents can spawn sub-agents for parallel work.\n- **Human-in-the-Loop** — Event-driven approval system pauses execution for user approval before sensitive actions (emails, calendar events, phone calls), then resumes in a new run\n- **Dynamic Memory** — Google Drive files (any `.md` file — soul.md, preferences.md, project-notes.md) + Supermemory semantic search across all memory files\n- **Heartbeat Scheduler** — Configurable intervals with checklist-driven tasks, active hours, and HEARTBEAT.md support from Google Drive\n- **Multi-Provider LLM** — OpenAI (GPT-5.2, GPT-5, GPT-5 Mini) and Anthropic (Claude Opus 4.6, Sonnet 4.6, Haiku 4.5) with per-agent model selection and per-user encrypted API keys\n- **Skills System** — Markdown-based skills (SKILL.md) for capabilities like email digest, outreach campaigns, and job applications — enable with one click\n- **Modular Tool System** — 20 tools organized into modules (core, research, memory, google, browser, telegram) loaded dynamically based on agent config\n- **Multi-User SaaS** — Google OAuth, per-user data isolation, encrypted per-user API keys for every integration, ownership checks on all API routes\n\n## How It Works\n\n### Agent Lifecycle\n\n```\nSign Up → Agent Auto-Created → [Disabled]\n                                    │\n                                 Enable\n                                    ▼\n                              [Enabled, Idle]  ← \"Listening...\"\n                                │         ▲\n                           Chat /      Workflow\n                        Heartbeat /    completes\n                         Welcome          │\n                                ▼         │\n                           [Enabled, Active]  ← \"Running...\"\n```\n\n1. **Sign Up** — Your personal agent is auto-created on first login. No manual setup needed.\n2. **Enable** — Agent introduces itself via a welcome workflow, then listens for chat messages and heartbeats.\n3. **Chat** — Send a message and the agent runs a workflow to respond and take action.\n4. **Heartbeat** — On schedule (with active hours), the agent checks its task list and acts only if needed.\n5. **Sub-Agents** — Your agent can spawn async sub-agents for parallel research and tasks (max depth: 3).\n6. **Disable** — Agent stops gracefully, mid-workflow if necessary.\n\n### Memory System\n\nAgents have persistent memory stored in your Google Drive:\n\n| File | Purpose | Auto-loaded |\n|------|---------|-------------|\n| `soul.md` | Agent personality and identity | Yes |\n| `preferences.md` | Learned user preferences | Yes |\n| `knowledge.md` | Accumulated research | On request |\n| `journal.md` | Activity log | On request |\n| Custom `.md` files | Anything the agent creates | On request |\n\nAgents can also **append** to files (for journals and notes) and **semantically search** across all memory files via Supermemory integration.\n\n### Human-in-the-Loop\n\nSensitive actions require your approval before execution:\n\n- **Emails** — Agent drafts, you approve or edit before sending\n- **Calendar Events** — Agent proposes, you confirm\n- **Phone Calls** — Agent requests, you authorize\n- **Questions** — Agent asks for clarification, chat drawer auto-opens\n\n## Features\n\n| Feature | Status |\n|---------|--------|\n| Google OAuth authentication | Stable |\n| Multi-user data isolation + ownership checks | Stable |\n| Single agent per user with auto-creation | Stable |\n| Modular tool system (20 tools in lib/ai/tools/) | Stable |\n| Async workflow execution with background runs | Stable |\n| Trigger-aware prompts (welcome/chat/heartbeat/manual) | Stable |\n| Web research (Firecrawl search + scrape) | Stable |\n| Semantic memory search (Supermemory) | Stable |\n| Dynamic memory files (create any .md file) | Stable |\n| Memory append mode (incremental writes) | Stable |\n| Human-in-the-loop event-driven approvals | Stable |\n| Activity feed + real-time metrics (SSE) | Stable |\n| Per-user encrypted API keys (AES-GCM) for all integrations | Stable |\n| Chat interface with chat-triggered workflows | Stable |\n| Heartbeat scheduler (background agents) | Stable |\n| Skills system (6 SKILL.md-based skills) | Stable |\n| Multi-provider LLM (OpenAI + Anthropic) | Stable |\n| Agent analytics | Stable |\n| Google Drive memory (per-agent files) | Stable |\n| Async sub-agent spawning (max depth 3) | Stable |\n| Active hours for heartbeat schedules | Stable |\n| Gmail (send, search) | Stable |\n| Google Calendar (list, create events) | Stable |\n| Telegram bot (send/receive messages) | Stable |\n| Browser automation (Browser-Use Cloud) | Stable |\n| Voice calls (Twilio) | Needs testing |\n| Knowledge graph visualization | Preview |\n\n## Architecture\n\n```\nNext.js 16 App Router\n├── Dashboard UI (React 19, Tailwind CSS 4, shadcn/ui)\n├── API Routes (REST endpoints, 40+, all with ownership checks)\n├── Agent Execution Engine (plain async + event-driven HITL)\n│   ├── agent-workflow.ts    — Main workflow loop (async function)\n│   ├── steps.ts             — Step functions + tool handler dispatch\n│   ├── agent-runner.ts      — Background execution via waitUntil\n│   └── tools/               — 20 modular tool definitions + handlers\n│       ├── core/            — log-activity, ask-user, send-message, spawn/check sub-agent\n│       ├── research/        — start-session, plan-queries, firecrawl-research, complete-session\n│       ├── memory/          — read, update, append, search memory\n│       ├── google/          — send-email, search-emails, create/list calendar events\n│       ├── browser/         — browser-task\n│       └── telegram/        — send-telegram-message\n├── LLM Providers (per-user encrypted API keys)\n│   ├── OpenAI               — GPT-5.2, GPT-5, GPT-5 Mini\n│   └── Anthropic            — Claude Opus 4.6, Sonnet 4.6, Haiku 4.5\n├── Memory System\n│   ├── Google Drive          — Per-agent .md files (dynamic filenames, append mode)\n│   └── Supermemory           — Semantic search across all memory files\n├── Skills System (SKILL.md format)\n│   └── 6 skills             — Email digest, calendar, outreach, job search, briefing, research\n├── Integrations (all with per-user key resolution)\n│   ├── Firecrawl            — Web search + scraping\n│   ├── Supermemory          — Semantic memory storage + retrieval\n│   ├── Google APIs          — Gmail + Calendar + Drive via googleapis\n│   ├── Telegram             — Bot messaging via grammY\n│   ├── Browser-Use Cloud    — Browser automation\n│   └── Twilio               — Voice calls\n├── Scheduler\n│   └── Heartbeat            — Vercel Cron (prod) / setInterval (dev), active hours, HEARTBEAT.md\n└── Database                  — Neon Postgres (serverless), 19 migrations\n```\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 20+\n- pnpm\n- A [Neon](https://neon.tech) Postgres database\n- A [Google Cloud](https://console.cloud.google.com) project with OAuth credentials\n- An [OpenAI](https://platform.openai.com) API key\n\n### 1. Clone and install\n\n```bash\ngit clone https://github.com/shuruheel/volition.git\ncd volition\npnpm install\n```\n\n### 2. Configure environment\n\n```bash\ncp env.example .env.local\n```\n\nEdit `.env.local` with your credentials. See [docs/SETUP.md](docs/SETUP.md) for detailed setup instructions.\n\nRequired variables:\n- `DATABASE_URL` — Neon Postgres connection string\n- `OPENAI_API_KEY` — OpenAI API key (or configure per-user in Settings)\n- `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` — Google OAuth credentials\n- `AUTH_SECRET` — NextAuth secret (generate with `openssl rand -base64 32`)\n- `NEXT_PUBLIC_APP_URL` — Your app URL\n\n### 3. Set up the database\n\n```bash\npnpm db:setup\n```\n\nThis runs all 19 migrations to create the schema.\n\n### 4. Start the dev server\n\n```bash\npnpm dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000).\n\n### 5. Try it out\n\n1. Sign in with Google\n2. Enter your OpenAI API key on the onboarding screen\n3. Your personal agent is auto-created — enable it on the dashboard\n4. Chat with the agent to give it tasks\n5. Enable skills (email digest, research, etc.) on the Skills page\n6. Configure heartbeat schedule, identity, and model in Settings\n7. Watch it research, take actions, and ask for approval on sensitive operations\n\n## Pages\n\n| Page | URL | Description |\n|------|-----|-------------|\n| Landing | `/` | Product landing page |\n| Login | `/login` | Google OAuth sign-in |\n| Onboarding | `/onboarding` | OpenAI API key setup |\n| Dashboard | `/dashboard` | Single agent activity feed + status |\n| Skills | `/skills` | Browse and enable skills for your agent |\n| Settings | `/settings` | Agent identity, heartbeat config, model selection, API keys |\n| Chat | `/chat` | Direct chat with your agent |\n| Graph | `/graph` | Knowledge graph visualization |\n\n## Skills\n\nEnable pre-built capabilities on your agent (defined as SKILL.md files):\n\n- **Email Digest** — Summarize unread emails, highlight action items\n- **Calendar Summary** — Daily calendar briefing with meeting prep\n- **Outreach Campaign** — Automated personalized email outreach\n- **Job Application Prep** — Research companies, tailor resume, draft cover letters\n- **Daily Intelligence Briefing** — Monitor sources, synthesize, deliver via email\n- **Research Deep Dive** — Multi-session comprehensive research\n\n## Security\n\n- **Authentication** — Google OAuth via NextAuth.js v5 with JWT sessions\n- **Authorization** — `requireAgentOwnership()` and `requireActivityOwnership()` on all protected API routes\n- **Data Isolation** — All queries scoped to authenticated user's agents\n- **Encrypted Keys** — AES-GCM encryption for all API keys stored in database\n- **Per-User Keys** — Every integration resolves per-user keys from `tool_configs`, with env var fallback\n- **Google Drive Isolation** — Per-user OAuth tokens, `drive.file` scope (only accesses files Volition created)\n- **Telegram Validation** — Bot deep-links validate agent exists, is enabled, and has Telegram tool enabled\n\n## Development\n\n```bash\npnpm install          # Install dependencies\npnpm dev              # Dev server at http://localhost:3000\npnpm build            # Production build\npnpm lint             # ESLint\npnpm db:setup         # Run migrations\npnpm db:migrate       # Run migrations (alias)\n```\n\n### Adding New Tools\n\nTools are defined as modular files in `lib/ai/tools/` using the `ToolModule` interface — each file exports a `definition` (OpenAI JSON Schema), a `handler` function, and optional `requires`/`requiresAuth` fields. The registry (`lib/ai/tools/registry.ts`) assembles tools dynamically based on agent config. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.\n\n### Adding New LLM Providers\n\nCreate a new provider class implementing `LLMProvider` in `lib/ai/providers/`, register it in the factory at `lib/ai/providers/index.ts`, and add the provider to the model selector UI in `components/model-selector.tsx`.\n\n## Deployment\n\nSee [docs/SETUP.md](docs/SETUP.md) for detailed deployment instructions covering Vercel, Neon Postgres, Google Cloud OAuth, and optional integrations.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding conventions, and how to add new integrations.\n\n## License\n\n[MIT](LICENSE)\n"}