core
Turn rough requests into rigorously structured prompts β for any coding agent.
Installation
npx @agentforge-ai/coreAsk AI about core
Powered by Claude Β· Grounded in docs
I know everything about core. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
AgentForge
AgentForge is a TypeScript monorepo for building and operating self-hosted AI agents with a persistent Mastra runtime, a Convex-backed data layer, and CLI-driven local workflows.
The repository currently contains the framework packages, the local Convex app used during development, the default project template scaffolded by the CLI, and example projects.
Monorepo Layout
agentforge/
βββ packages/
β βββ cli/ # agentforge CLI and project scaffolding
β βββ runtime/ # Persistent Mastra daemon and channel adapters
β βββ core/ # Shared agent, sandbox, MCP, channel, A2A, voice primitives
β βββ web/ # Standalone dashboard package
βββ convex/ # Local Convex app copy used in repo development
βββ templates/default/ # Synced default project template assets
βββ examples/finforge/ # Example project
βββ docs/ # Project documentation
βββ tests/e2e/ # End-to-end test suite
The scaffolded project template source of truth lives under packages/cli/templates/default/, and Convex template changes must stay synced with the generated copies.
What Exists Today
@agentforge-ai/cli: scaffolds projects and provides the operational commands used during local development.@agentforge-ai/runtime: exports the daemon, agent factory, Convex-backed memory helpers, and HTTP/Discord/Telegram channel adapters.@agentforge-ai/core: exports shared agent primitives, sandboxing, MCP, channels, skills, A2A, research, workflows, voice, and browser tooling.@agentforge-ai/web: a package-specific dashboard app.convex/: the repoβs local Convex backend copy, which mirrors the default templateβs Convex layer.
CLI Surface
The CLI currently registers these command families from packages/cli/src/index.ts:
- Project lifecycle:
create,run,deploy,upgrade - Runtime:
start - Cloud/auth/config:
models,workspace,tokens,config,vault,keys,status - Agent and chat:
agents,chat,sessions,threads - Skills and orchestration:
skills,skill,cron,workflows,research - Data and files:
files,projects - Integrations:
mcp,channel:telegram,channel:whatsapp,channel:slack,channel:discord - Execution:
sandbox - Dashboard and logs:
dashboard,logsare registered from the status command module
Important behavior:
agentforge runstarts the local Convex development environment.agentforge startboots the persistent daemon and HTTP channel.agentforge chattalks to the daemon over the local HTTP/SSE endpoint.agentforge dashboardstarts a dashboard if it can find one in the project or repo layout.
Development
Prerequisites
- Node.js
>=18 - pnpm
>=8
Install Repo Dependencies
pnpm install
Standard Contributor Commands
Run these from the repo root while working on framework code:
pnpm build
pnpm test
pnpm typecheck
pnpm lint
When editing template-backed Convex files, sync the copies afterward:
pnpm sync-templates
Working On The Template Dashboard
packages/cli/templates/default/dashboard is not a workspace package. If you need to run or edit that dashboard directly, install its dependencies inside that directory:
cd packages/cli/templates/default/dashboard
pnpm install
pnpm dev
Start A Local AgentForge Project For Contribution
Use this flow when you need to validate the framework against a real project scaffold.
- Build the workspace packages from the repo root.
- Create a fresh project or use an existing scaffold.
- Configure the project
.env.local. - Start Convex.
- Start the AgentForge daemon.
- Chat with an agent and optionally start the dashboard.
Example flow:
# From the repo root
pnpm build
# Create a local test project
node packages/cli/dist/index.js create /tmp/agentforge-dev
cd /tmp/agentforge-dev
# Configure environment
cp .env.example .env.local
# Terminal 1: start Convex first
npx convex dev
# Terminal 2: start the daemon
agentforge start
# Terminal 3: talk to the daemon
agentforge chat
# Optional: start the dashboard if the project has a dashboard directory
agentforge dashboard
Environment And Startup Requirements
These requirements are enforced by the current command implementations:
CONVEX_URLmust exist beforeagentforge start. The command reads it from the environment or from.env.local, and it expectsnpx convex devto have been run first.- At least one agent must exist in Convex before
agentforge startcan boot usable runtime agents. agentforge chatrequires the daemon to already be running on the local HTTP port.agentforge dashboardonly starts if it can find a dashboard directory in the project, repo layout, or installed package path.
Documentation Map
- Getting Started
- CLI Reference
- Architecture
- Channels
- Skills
- MCP
- A2A
- Advanced Tools
- Multi-Agent Collaboration
- Deployment Guide
- Releasing
- Technical Reference
- FinForge Demo
- Competitive Positioning
Package Docs
- CLI package README
- Runtime package README
- Core package README
- Web package README
- Default template README
Testing
- Unit and package tests:
pnpm test - Type checking:
pnpm typecheck - End-to-end suite: see
tests/e2e/README.md
