AgentWeave
AgentWeave is a local application where several AI coding agents work on your projects together, against specifications you approve. It runs on your machine: one process owns execution, state and identity, and serves the interface you work in.
Requires Python 3.11+.
Quick start
pip install agentweave-ai
agentweave
That is the whole thing. agentweave-ai brings the Hub — the local server and its interface — with
it; there is no second package to install and no configuration to write.
The first launch creates user-local Hub state, runs database migrations, starts the native Hub,
registers the current directory as a project, and opens its overview at http://localhost:8000.
Run agentweave from another directory to add or reopen that project in the same instance.
Projects keep separate agents, conversations, tasks, settings, caches, and runtime workspaces.
CLI
The CLI manages only the local application instance:
agentweave # Start or open the app
agentweave doctor # Check installation and runtime readiness
agentweave status # Show instance URL, port, and project collection
agentweave stop # Stop the local instance
agentweave reset # Delete local Hub state after confirmation
agentweave --version
Messages, tasks, agents, jobs, questions, and project settings are managed through the dashboard or the run-authenticated agent capability plane—not CLI subcommands.
What the dashboard provides
- Agent roster, launch readiness, conversations, and streamed output
- Task board, messages, questions, and scheduled jobs
- Usage accounting, logs, traces, specifications, and project settings
- Direct Hub-owned execution for configured runners
- One least-privilege capability API, reached over HTTP or through equivalent MCP tools
Local state and configuration
The native instance stores state under ~/.agentweave/hub/:
.env— generated bootstrap identity and local configurationdata/agentweave.db— SQLite databasehub.pid— native process identity while running
Important environment settings include:
| Variable | Default | Purpose |
|---|---|---|
AW_BOOTSTRAP_API_KEY |
generated | Instance-local operator credential |
AW_BOOTSTRAP_PROJECT_ID |
unset | Legacy migration bootstrap only |
AW_WORKSPACE_ROOT |
unset | Container-visible project root in explicit Docker mode |
AW_WORKSPACE_HOST_ROOT |
./workspaces |
Host directory mounted at /workspaces by Compose |
AW_PORT |
8000 |
Hub port |
AW_HOST |
127.0.0.1 |
Native bind address |
DATABASE_URL |
generated SQLite URL | Database connection |
Provider credentials remain environment variables available to the Hub process. Secret values are never returned by readiness or diagnostic APIs.
Agent capability plane
Every running agent receives a short-lived run token. That identity can access only the project and agent actions permitted to that run, and is never accepted from a request body or header. Direct HTTP and MCP are two adapters over the same action set and authorization semantics — MCP because it is convenient, HTTP because some environments forbid MCP servers. The CLI is not one of them: it manages the local instance and has no agent capabilities.
Operator APIs use one instance credential and carry project identity in their URL; choosing a project is navigation, not authentication.
Development
pip install -e ./hub # first: agentweave-ai depends on agentweave-hub
pip install -e ".[dev]"
py -3.11 -m pytest tests/ -q
cd hub
py -3.11 -m pytest tests/ -q
cd ui
npm install
npm run test -- --run
npm run build
The Hub is installed first so pip resolves the dependency from this checkout rather than fetching a release from PyPI.
Exercise stateful product commands only inside testbed/ or another throwaway directory, and never
let this repository acquire a root agentweave.yml.
Repository layout
src/agentweave/ Python CLI and agent adapters
hub/hub/ FastAPI backend and Hub-owned execution
hub/ui/ React dashboard
tests/ CLI unit tests
hub/tests/ Hub tests
docs/ MkDocs documentation
openspec/ Current specifications and changes
Links
1 maintainer
Release files for agentweave-ai 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| agentweave_ai-1.1.0.tar.gz | 186.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agentweave_ai-1.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 334.8 kB
Release files / agentweave_ai-1.1.0.tar.gz
| Download URL | agentweave_ai-1.1.0.tar.gz |
|---|---|
| Size | 186.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
86e0ec9ddd9a3f0a988e5b4d4d0f506046deeb9befdf549ffe4bcf68bf88faad
|
|
BLAKE2b-256 checksum How to use checksums |
b6e42669f81e993eaf3e784c677d08476980c8d86ca5d2fb99249a24c77a153d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.15
|
Release files / agentweave_ai-1.1.0-py3-none-any.whl
| Download URL | agentweave_ai-1.1.0-py3-none-any.whl |
|---|---|
| Size | 148.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d66cc78e26bb103983bdda165abe6cc32700582d82d13dce8924a67f61dc1f5f
|
|
BLAKE2b-256 checksum How to use checksums |
794c618b6478e7031cfa620a8b8509203d34bcbc7cfecda91bff42f2464821c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.15
|
