clawdi 0.3.2 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +271 -62
- package/dist/index.js +180 -164
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,89 +1,298 @@
|
|
|
1
|
-
|
|
1
|
+
<h1 align="center">Clawdi</h1>
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<p align="center">
|
|
4
|
+
<strong>The best home for all your AI agents — environments, sessions, memory, skills, cron jobs, and app connections.</strong>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<a href="https://www.npmjs.com/package/clawdi"><img src="https://img.shields.io/npm/v/clawdi?style=for-the-badge&logo=npm&color=cb3837" alt="npm version"></a>
|
|
9
|
+
<a href="https://github.com/Clawdi-AI/clawdi/actions/workflows/cli-publish.yml"><img src="https://img.shields.io/github/actions/workflow/status/Clawdi-AI/clawdi/cli-publish.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=CI" alt="CI status"></a>
|
|
10
|
+
<a href="https://github.com/Clawdi-AI/clawdi/stargazers"><img src="https://img.shields.io/github/stars/Clawdi-AI/clawdi?style=for-the-badge&logo=github" alt="GitHub stars"></a>
|
|
11
|
+
<a href="https://github.com/Clawdi-AI/clawdi/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
|
|
12
|
+
</p>
|
|
13
|
+
|
|
14
|
+
<p align="center">
|
|
15
|
+
<a href="https://clawdi.ai">Website</a> ·
|
|
16
|
+
<a href="https://github.com/Clawdi-AI/clawdi">GitHub</a> ·
|
|
17
|
+
<a href="https://www.npmjs.com/package/clawdi">npm</a> ·
|
|
18
|
+
<a href="https://github.com/Clawdi-AI/clawdi/blob/main/docs/architecture.md">Architecture</a> ·
|
|
19
|
+
<a href="#quickstart">Quickstart</a> ·
|
|
20
|
+
<a href="#cli-reference">CLI Reference</a> ·
|
|
21
|
+
<a href="#troubleshooting">Troubleshooting</a>
|
|
22
|
+
</p>
|
|
23
|
+
|
|
24
|
+
<p align="center">
|
|
25
|
+
<img src="https://raw.githubusercontent.com/Clawdi-AI/clawdi/main/docs/images/dashboard-preview.png" alt="Clawdi dashboard" width="900">
|
|
26
|
+
</p>
|
|
27
|
+
|
|
28
|
+
> Think of Clawdi as iCloud for AI agents — install once on any device, and your Claude Code, Codex, Hermes, and OpenClaw agents share the same memory, secrets, skills, sessions, and app connections. Switch frameworks or machines; nothing gets lost.
|
|
29
|
+
|
|
30
|
+
The fastest way to try it is hosted Clawdi Cloud. The whole stack is also here: MIT-licensed CLI, FastAPI backend, Next.js dashboard, database schema, migrations, and docs. Use the hosted service, self-host it, fork it, or build your own agent sync layer from the pieces.
|
|
4
31
|
|
|
5
32
|
## Quickstart
|
|
6
33
|
|
|
7
34
|
```bash
|
|
8
|
-
|
|
35
|
+
npm i -g clawdi
|
|
36
|
+
|
|
37
|
+
clawdi auth login
|
|
38
|
+
clawdi setup
|
|
39
|
+
clawdi doctor
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
That gets you:
|
|
43
|
+
|
|
44
|
+
- Browser-based login to Clawdi Cloud
|
|
45
|
+
- Agent auto-detection for Claude Code, Codex, Hermes, and OpenClaw
|
|
46
|
+
- MCP registration so your agent can call Clawdi tools
|
|
47
|
+
- The bundled `clawdi` skill installed into each detected agent
|
|
48
|
+
- A health check that verifies auth, agent paths, vault access, and MCP config
|
|
49
|
+
|
|
50
|
+
By default the CLI talks to hosted Clawdi Cloud. Want to run your own backend? See [Own the Stack](#own-the-stack).
|
|
51
|
+
|
|
52
|
+
Requires Node ≥ 22.5 (the CLI uses the built-in `node:sqlite` module).
|
|
53
|
+
|
|
54
|
+
You can also try without installing:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
9
57
|
npx clawdi --help
|
|
58
|
+
```
|
|
10
59
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
clawdi
|
|
15
|
-
clawdi doctor # verify everything's wired up
|
|
60
|
+
Headless environment? Use the manual flow:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
clawdi auth login --manual
|
|
16
64
|
```
|
|
17
65
|
|
|
18
|
-
|
|
66
|
+
## Why Clawdi
|
|
67
|
+
|
|
68
|
+
AI agents are still treated like isolated apps. Claude Code has one set of sessions and instructions. Codex has another. Secrets sit in shell profiles and `.env` files. Useful memories get trapped in whichever agent happened to learn them. App integrations get rebuilt from scratch every time you switch tools.
|
|
69
|
+
|
|
70
|
+
Clawdi is the shared layer underneath:
|
|
71
|
+
|
|
72
|
+
- **Cross-agent memory** — Store durable preferences, decisions, facts, and project context once. Search them from any connected agent.
|
|
73
|
+
- **Portable skills** — Upload or install agent instructions once, then sync them into every registered agent.
|
|
74
|
+
- **Session sync** — Push local session history to the dashboard for review and recall.
|
|
75
|
+
- **Vault secrets** — Store secrets server-side and inject them only when running a command.
|
|
76
|
+
- **App connections** — Hook agents into Notion, Gmail, Drive, Calendar, Linear, GitHub, and more from the dashboard. Tools show up inside every connected agent automatically over MCP.
|
|
77
|
+
- **MCP tools** — Memory, vault, and connector tools served through the Model Context Protocol so any MCP-aware agent can use them.
|
|
19
78
|
|
|
20
|
-
|
|
79
|
+
In practice — teach one agent something:
|
|
21
80
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
81
|
+
```text
|
|
82
|
+
remember that this repo uses Bun for TypeScript and PDM for backend scripts
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Later, in a different agent or a fresh session, ask "what package manager should I use here?" — it can call Clawdi memory search and answer from your actual context instead of guessing.
|
|
86
|
+
|
|
87
|
+
Run a command with vault secrets without putting them on disk:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
clawdi vault set OPENAI_API_KEY
|
|
91
|
+
clawdi run -- python scripts/ingest.py
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Install a shared skill into every registered agent at once:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
clawdi skill install anthropics/skills/artifacts-builder
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Roadmap
|
|
101
|
+
|
|
102
|
+
Today Clawdi gives one person a shared layer across their agents. Two bigger bets come next.
|
|
103
|
+
|
|
104
|
+
The first is autonomy. Agents should work without you at the keyboard.
|
|
105
|
+
|
|
106
|
+
- Cron jobs for recurring agent runs.
|
|
107
|
+
- Remote control for agents on any of your machines.
|
|
108
|
+
- Automatic memory built from session history.
|
|
109
|
+
|
|
110
|
+
The second is making Clawdi multi-player. Today every Clawdi belongs to one person. That's the wrong shape for teams.
|
|
111
|
+
|
|
112
|
+
- Shared memory, skills, and connections, with access controls.
|
|
113
|
+
- An agent-to-agent channel for handoff and ask-for-help.
|
|
114
|
+
- Task tracking that every connected agent can use.
|
|
115
|
+
|
|
116
|
+
We'll also keep adding adapters. Cursor, OpenCode, Amp, Pi, and others. The same memory, skills, and connections follow you everywhere.
|
|
117
|
+
|
|
118
|
+
Want any of this sooner? [Open an issue](https://github.com/Clawdi-AI/clawdi/issues). What's loud is what we build first.
|
|
119
|
+
|
|
120
|
+
## Hosted or Self-Hosted
|
|
121
|
+
|
|
122
|
+
Clawdi has two intended paths.
|
|
123
|
+
|
|
124
|
+
### Use Clawdi Cloud
|
|
125
|
+
|
|
126
|
+
Best for trying it in minutes.
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
npm i -g clawdi
|
|
130
|
+
clawdi auth login
|
|
131
|
+
clawdi setup
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
The published CLI defaults to the hosted API. You get the least setup friction and can focus on wiring agents, memories, skills, and vault secrets.
|
|
135
|
+
|
|
136
|
+
### Own the Stack
|
|
137
|
+
|
|
138
|
+
Best when you want to inspect, modify, self-host, or build on Clawdi.
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
git clone https://github.com/Clawdi-AI/clawdi.git
|
|
142
|
+
cd clawdi
|
|
143
|
+
bun install
|
|
144
|
+
docker compose up -d postgres
|
|
145
|
+
```
|
|
25
146
|
|
|
26
|
-
|
|
147
|
+
Then run the backend and dashboard locally:
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
cd backend
|
|
151
|
+
cp .env.example .env
|
|
152
|
+
pdm install
|
|
153
|
+
pdm migrate
|
|
154
|
+
pdm dev
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
cd ../apps/web
|
|
159
|
+
cp .env.example .env.local
|
|
160
|
+
bun run dev
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Point your CLI at your local backend:
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
clawdi config set apiUrl http://localhost:8000
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Local self-hosting currently expects:
|
|
170
|
+
|
|
171
|
+
- Node.js 22.5+ and Bun 1.3+
|
|
172
|
+
- Python 3.12 with PDM
|
|
173
|
+
- PostgreSQL 16 with `pg_trgm` and `pgvector`
|
|
174
|
+
- Clerk keys for dashboard auth
|
|
175
|
+
- Two generated encryption keys for vault data and MCP proxy JWTs
|
|
176
|
+
|
|
177
|
+
See [`backend/.env.example`](https://github.com/Clawdi-AI/clawdi/blob/main/backend/.env.example) and [`apps/web/.env.example`](https://github.com/Clawdi-AI/clawdi/blob/main/apps/web/.env.example) for the exact environment variables.
|
|
178
|
+
|
|
179
|
+
## What Is In This Repo
|
|
180
|
+
|
|
181
|
+
```text
|
|
182
|
+
apps/web/ Next.js 16 dashboard with Clerk auth, shadcn/ui, Tailwind v4
|
|
183
|
+
packages/cli/ Published `clawdi` CLI, agent adapters, and MCP server
|
|
184
|
+
packages/shared/ Shared API types, schemas, and constants
|
|
185
|
+
backend/ FastAPI backend, SQLAlchemy models, Alembic migrations
|
|
186
|
+
docs/ Architecture notes, scenarios, and development guides
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
The system is deliberately boring where it should be:
|
|
190
|
+
|
|
191
|
+
- FastAPI API server
|
|
192
|
+
- PostgreSQL for structured data and memory search
|
|
193
|
+
- File storage for session and skill bodies
|
|
194
|
+
- Local CLI state under `~/.clawdi`
|
|
195
|
+
- MCP stdio server spawned by each agent
|
|
196
|
+
- No Redis, Celery, or hidden worker fleet required for the core local stack
|
|
197
|
+
|
|
198
|
+
For the deeper map, read [`docs/architecture.md`](https://github.com/Clawdi-AI/clawdi/blob/main/docs/architecture.md).
|
|
199
|
+
|
|
200
|
+
## Supported Agents
|
|
201
|
+
|
|
202
|
+
| Agent | Sessions | Skills | MCP setup |
|
|
203
|
+
| --- | --- | --- | --- |
|
|
204
|
+
| Claude Code | Yes | Yes | Automatic |
|
|
205
|
+
| Codex | Yes | Yes | Automatic |
|
|
206
|
+
| Hermes | Yes | Yes | Automatic |
|
|
207
|
+
| OpenClaw | Yes | Yes | Manual MCP hint where required |
|
|
208
|
+
|
|
209
|
+
Each agent has a dedicated adapter in [`packages/cli/src/adapters`](https://github.com/Clawdi-AI/clawdi/tree/main/packages/cli/src/adapters). Adding another agent means implementing the same adapter shape: detect it, read sessions, read/write skills, and define how commands run with injected env.
|
|
210
|
+
|
|
211
|
+
## CLI Reference
|
|
27
212
|
|
|
28
213
|
| Command | What it does |
|
|
29
214
|
| --- | --- |
|
|
30
|
-
| `clawdi auth login` / `logout` | Authenticate
|
|
31
|
-
| `clawdi status [--json]` | Show auth
|
|
32
|
-
| `clawdi
|
|
33
|
-
| `clawdi
|
|
34
|
-
| `clawdi
|
|
35
|
-
| `clawdi
|
|
36
|
-
| `clawdi
|
|
37
|
-
| `clawdi skill list
|
|
38
|
-
| `clawdi
|
|
39
|
-
| `clawdi
|
|
40
|
-
| `clawdi
|
|
41
|
-
| `clawdi
|
|
42
|
-
| `clawdi
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
| `clawdi vault set <key>` / `list [--json]` / `import <file>` | Manage secrets |
|
|
46
|
-
| `clawdi run -- <cmd>` | Run a command with vault secrets injected into env |
|
|
47
|
-
| `clawdi doctor [--json]` | Diagnose auth, agent paths, vault, MCP connectivity |
|
|
48
|
-
| `clawdi update [--json]` | Check for a newer CLI version |
|
|
49
|
-
| `clawdi mcp` | Start MCP server (stdio transport, for agents) |
|
|
50
|
-
|
|
51
|
-
Run any command with `--help` to see its flags and real examples.
|
|
52
|
-
|
|
53
|
-
## Environment variables
|
|
54
|
-
|
|
55
|
-
| Variable | Purpose |
|
|
56
|
-
| --- | --- |
|
|
57
|
-
| `CLAWDI_API_URL` | Override the backend endpoint (production builds default to `https://cloud-api.clawdi.ai`; from-source dev defaults to `http://localhost:8000`) |
|
|
58
|
-
| `CLAWDI_DEBUG` | Print stack traces on errors |
|
|
59
|
-
| `CLAWDI_NO_UPDATE_CHECK` | Suppress the non-blocking update check |
|
|
60
|
-
| `CLAWDI_NO_AUTO_UPDATE` | Skip the default-on background auto-updater. Persistent equivalent: `clawdi config set autoUpdate false` |
|
|
61
|
-
| `CLAUDE_CONFIG_DIR` | Custom home for the Claude Code adapter (instead of `~/.claude`) |
|
|
62
|
-
| `CODEX_HOME` | Custom home for the Codex adapter (instead of `~/.codex`) |
|
|
63
|
-
| `HERMES_HOME` | Custom home for the Hermes adapter (instead of `~/.hermes`) |
|
|
64
|
-
| `OPENCLAW_STATE_DIR` | Custom OpenClaw state directory |
|
|
65
|
-
| `OPENCLAW_AGENT_ID` | Target a specific OpenClaw agent (default `main`) |
|
|
66
|
-
| `CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `CIRCLECI`, `TRAVIS`, `BUILDKITE`, `JENKINS_URL`, `TEAMCITY_VERSION` | Detected as CI; interactive prompts are disabled |
|
|
215
|
+
| `clawdi auth login` / `logout` | Authenticate this machine |
|
|
216
|
+
| `clawdi status [--json]` | Show auth and sync state |
|
|
217
|
+
| `clawdi setup [--agent <type>]` | Register local agents, install MCP, install the bundled skill |
|
|
218
|
+
| `clawdi teardown [--agent <type>]` | Remove Clawdi's local agent wiring |
|
|
219
|
+
| `clawdi push` | Upload sessions and skills |
|
|
220
|
+
| `clawdi pull` | Download cloud skills into registered agents |
|
|
221
|
+
| `clawdi memory list/search/add/rm` | Manage cross-agent long-term memory |
|
|
222
|
+
| `clawdi skill list/add/install/rm/init` | Manage portable skills |
|
|
223
|
+
| `clawdi vault set/list/import` | Manage encrypted secrets |
|
|
224
|
+
| `clawdi run -- <cmd>` | Run a command with vault secrets injected |
|
|
225
|
+
| `clawdi doctor` | Diagnose auth, agent paths, vault, and MCP config |
|
|
226
|
+
| `clawdi update` | Check for a newer CLI version |
|
|
227
|
+
| `clawdi mcp` | Start the MCP stdio server used by agents |
|
|
228
|
+
|
|
229
|
+
Every command supports `--help`.
|
|
67
230
|
|
|
68
|
-
|
|
231
|
+
App connections are configured in the [Clawdi Cloud dashboard](https://clawdi.ai) and surface inside agents automatically over MCP — there is no CLI command to manage them.
|
|
69
232
|
|
|
70
|
-
|
|
233
|
+
## Development
|
|
71
234
|
|
|
235
|
+
Install dependencies:
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
bun install
|
|
72
239
|
```
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
└── update.json cached npm registry lookup
|
|
240
|
+
|
|
241
|
+
Run the web app and workspace dev tasks:
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
bun run dev
|
|
79
245
|
```
|
|
80
246
|
|
|
81
|
-
|
|
247
|
+
Run the backend:
|
|
248
|
+
|
|
249
|
+
```bash
|
|
250
|
+
cd backend
|
|
251
|
+
pdm dev
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
Run checks:
|
|
255
|
+
|
|
256
|
+
```bash
|
|
257
|
+
bun run check
|
|
258
|
+
bun run typecheck
|
|
259
|
+
|
|
260
|
+
cd backend
|
|
261
|
+
pdm lint
|
|
262
|
+
pdm test
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Run the CLI from source:
|
|
266
|
+
|
|
267
|
+
```bash
|
|
268
|
+
bun run packages/cli/src/index.ts --help
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Build and link the CLI locally:
|
|
272
|
+
|
|
273
|
+
```bash
|
|
274
|
+
cd packages/cli
|
|
275
|
+
bun run build
|
|
276
|
+
bun link
|
|
277
|
+
clawdi --version
|
|
278
|
+
```
|
|
82
279
|
|
|
83
280
|
## Troubleshooting
|
|
84
281
|
|
|
282
|
+
Run the diagnostic first:
|
|
283
|
+
|
|
85
284
|
```bash
|
|
86
|
-
clawdi doctor
|
|
285
|
+
clawdi doctor
|
|
87
286
|
```
|
|
88
287
|
|
|
89
|
-
|
|
288
|
+
Common issues:
|
|
289
|
+
|
|
290
|
+
- **`clawdi auth login` fails** - Re-run login, or use `clawdi auth login --manual` in headless environments.
|
|
291
|
+
- **No supported agent detected** - Install a supported agent or pass `--agent claude_code`, `--agent codex`, `--agent hermes`, or `--agent openclaw`.
|
|
292
|
+
- **Memory search is empty** - Add a memory first with `clawdi memory add "..."`, then verify with `clawdi memory search "..."`.
|
|
293
|
+
- **Local backend cannot start because `vector` is missing** - Install `pgvector` for your PostgreSQL 16 instance, or use the included Docker Compose database.
|
|
294
|
+
- **Agent MCP tools look stale** - Run `clawdi setup --agent <type>` again and restart the agent.
|
|
295
|
+
|
|
296
|
+
## License
|
|
297
|
+
|
|
298
|
+
MIT. See [`LICENSE`](https://github.com/Clawdi-AI/clawdi/blob/main/LICENSE).
|