@praveencs/agent 0.9.25 โ 0.9.26
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 +359 -418
- package/docs/DOCUMENTATION.md +748 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,597 +1,538 @@
|
|
|
1
1
|
# ๐ค Agent Runtime
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> **Your autonomous AI employee.** Give it a goal, walk away. It decomposes, executes, scripts, and learns โ all by itself.
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@praveencs/agent)
|
|
6
6
|
[](LICENSE)
|
|
7
7
|
|
|
8
8
|
```
|
|
9
|
+
$ npm install -g @praveencs/agent
|
|
10
|
+
$ agent init
|
|
9
11
|
$ agent
|
|
10
12
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
โ Project: my-app โ
|
|
14
|
-
โ Model: gpt-4o โ 3 skills โ 2 commands โ
|
|
15
|
-
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
|
|
13
|
+
๐ค Agent Runtime v0.9.25
|
|
14
|
+
> Build a system health dashboard with monitoring scripts
|
|
16
15
|
|
|
17
|
-
|
|
16
|
+
๐ง Decomposing into 5 subtasks...
|
|
17
|
+
โก [1/5] Create project structure โ
|
|
18
|
+
โก [2/5] Gather system data โ โ created .agent/scripts/system-info/
|
|
19
|
+
โก [3/5] Build HTML dashboard โ โ created dashboard.html + dashboard.css
|
|
20
|
+
โก [4/5] Create update script โ โ created .agent/scripts/update-dashboard/
|
|
21
|
+
โก [5/5] Write README โ
|
|
18
22
|
|
|
19
|
-
|
|
20
|
-
โ Thinking...
|
|
21
|
-
โก fs.read(src/auth/handler.ts) โ
|
|
22
|
-
โก fs.write(src/auth/jwt.ts) โ
|
|
23
|
-
โก cmd.run(npm test) โ
|
|
24
|
-
|
|
25
|
-
โ Done (12.3s)
|
|
26
|
-
|
|
27
|
-
> /deploy-staging
|
|
28
|
-
Running command: deploy-staging...
|
|
23
|
+
โ Goal completed (42.1s) โ 5/5 tasks done
|
|
29
24
|
```
|
|
30
25
|
|
|
31
26
|
---
|
|
32
27
|
|
|
33
|
-
##
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
| **๐พ Persistent Memory** | SQLite + FTS5 semantic memory across sessions |
|
|
47
|
-
| **โค๏ธ Self-Improvement** | Monitors skill metrics and auto-patches failing skills |
|
|
48
|
-
| **๐ Reporting** | Daily standup reports and AI-generated executive summaries |
|
|
49
|
-
| **๐ Policy Engine** | Permission-gated tool execution with human-in-the-loop approval |
|
|
28
|
+
## What Is This?
|
|
29
|
+
|
|
30
|
+
Agent Runtime is a **fully autonomous AI coding agent** that runs on your machine. Unlike chat-based tools where you prompt-and-wait, this agent:
|
|
31
|
+
|
|
32
|
+
1. **Breaks down complex goals** into a dependency-aware task graph
|
|
33
|
+
2. **Runs tasks in parallel** (up to 3 at once) with automatic retries
|
|
34
|
+
3. **Creates scripts and files** autonomously โ shell, Python, Node.js
|
|
35
|
+
4. **Uses your credentials** securely from an encrypted vault
|
|
36
|
+
5. **Re-plans on failure** โ if a task fails, the LLM suggests alternatives
|
|
37
|
+
6. **Remembers everything** โ persistent SQLite memory across sessions
|
|
38
|
+
7. **Has a web dashboard** โ Agent Studio for visual management
|
|
39
|
+
|
|
40
|
+
Think of it as a **junior developer you can assign tasks to** and check on later.
|
|
50
41
|
|
|
51
42
|
---
|
|
52
43
|
|
|
53
|
-
##
|
|
44
|
+
## ๐ Quick Start (5 minutes)
|
|
45
|
+
|
|
46
|
+
### 1. Install
|
|
54
47
|
|
|
55
48
|
```bash
|
|
56
49
|
npm install -g @praveencs/agent
|
|
57
50
|
```
|
|
58
51
|
|
|
59
|
-
###
|
|
52
|
+
### 2. Initialize a project
|
|
60
53
|
|
|
61
54
|
```bash
|
|
62
|
-
|
|
55
|
+
cd your-project
|
|
63
56
|
agent init
|
|
64
|
-
|
|
65
|
-
# Launch interactive mode (recommended)
|
|
66
|
-
agent
|
|
67
|
-
|
|
68
|
-
# Or run a one-off goal
|
|
69
|
-
agent run "Add input validation to the signup form"
|
|
70
57
|
```
|
|
71
58
|
|
|
72
|
-
|
|
59
|
+
This creates a `.agent/` directory with configuration, skills, commands, and scripts.
|
|
73
60
|
|
|
74
|
-
|
|
61
|
+
### 3. Configure your LLM
|
|
75
62
|
|
|
76
63
|
```bash
|
|
77
|
-
# Set
|
|
64
|
+
# Set your preferred LLM provider
|
|
78
65
|
export OPENAI_API_KEY=sk-...
|
|
66
|
+
# OR
|
|
79
67
|
export ANTHROPIC_API_KEY=sk-ant-...
|
|
80
|
-
|
|
81
|
-
# Or configure directly
|
|
82
|
-
agent config --init
|
|
83
68
|
```
|
|
84
69
|
|
|
85
|
-
|
|
70
|
+
The agent supports **OpenAI**, **Anthropic**, **Azure OpenAI**, and **Ollama** (local) with automatic fallback.
|
|
86
71
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
### 1. Interactive Mode (Recommended)
|
|
90
|
-
|
|
91
|
-
Type `agent` with no arguments to enter the **Interactive REPL**:
|
|
72
|
+
### 4. Start using it
|
|
92
73
|
|
|
93
74
|
```bash
|
|
75
|
+
# Interactive mode (recommended)
|
|
94
76
|
agent
|
|
95
|
-
```
|
|
96
77
|
|
|
97
|
-
|
|
78
|
+
# Or one-shot command
|
|
79
|
+
agent run "Add input validation to the signup form"
|
|
98
80
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
> Now write tests for it
|
|
102
|
-
> /deploy-staging
|
|
81
|
+
# Or start the background daemon
|
|
82
|
+
agent daemon start
|
|
103
83
|
```
|
|
104
84
|
|
|
105
|
-
|
|
85
|
+
---
|
|
106
86
|
|
|
107
|
-
|
|
87
|
+
## ๐ How It Works
|
|
108
88
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
89
|
+
### The Agent Loop
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
You give a goal
|
|
93
|
+
โ
|
|
94
|
+
๐ง LLM decomposes it into subtasks with dependencies
|
|
95
|
+
โ
|
|
96
|
+
โก Daemon picks up tasks (up to 3 in parallel)
|
|
97
|
+
โ
|
|
98
|
+
๐ง Each task uses tools: file system, shell, git, HTTP, scripts, credentials
|
|
99
|
+
โ
|
|
100
|
+
โ
On success โ saves output, triggers dependent tasks
|
|
101
|
+
โ On failure โ retries 3x, then re-decomposes with LLM
|
|
102
|
+
โ
|
|
103
|
+
๐พ Everything stored in memory for future context
|
|
104
|
+
```
|
|
120
105
|
|
|
121
|
-
|
|
106
|
+
### Available Tools
|
|
122
107
|
|
|
123
|
-
|
|
108
|
+
The agent has access to these tools when executing tasks:
|
|
109
|
+
|
|
110
|
+
| Tool | What It Does |
|
|
111
|
+
|------|-------------|
|
|
112
|
+
| `fs.read` / `fs.write` | Read and write files |
|
|
113
|
+
| `fs.mkdir` / `fs.list` | Create directories, list contents |
|
|
114
|
+
| `cmd.run` | Execute shell commands |
|
|
115
|
+
| `git.status` / `git.diff` / `git.commit` | Git operations |
|
|
116
|
+
| `http.request` | Make HTTP API calls (GET/POST/PUT/DELETE) |
|
|
117
|
+
| `secrets.get` / `secrets.list` | Access encrypted credentials |
|
|
118
|
+
| `script.run` | Execute project scripts by name |
|
|
119
|
+
| `command.execute` | Run pre-defined command workflows |
|
|
124
120
|
|
|
125
121
|
---
|
|
126
122
|
|
|
127
|
-
|
|
123
|
+
## ๐ฏ Goal-Driven Autonomy
|
|
128
124
|
|
|
129
|
-
|
|
125
|
+
### Creating Goals
|
|
130
126
|
|
|
131
127
|
```bash
|
|
132
|
-
|
|
133
|
-
agent
|
|
134
|
-
|
|
128
|
+
# From CLI
|
|
129
|
+
agent goal add "Build authentication with OAuth2" --priority 1
|
|
130
|
+
|
|
131
|
+
# The LLM auto-decomposes it:
|
|
132
|
+
# Task 1: Set up OAuth2 dependencies
|
|
133
|
+
# Task 2: Create auth routes (depends on: 1)
|
|
134
|
+
# Task 3: Implement token exchange (depends on: 1)
|
|
135
|
+
# Task 4: Add middleware (depends on: 2, 3)
|
|
136
|
+
# Task 5: Write tests (depends on: 4)
|
|
135
137
|
```
|
|
136
138
|
|
|
137
|
-
|
|
139
|
+
### The Daemon
|
|
138
140
|
|
|
139
|
-
|
|
141
|
+
The daemon is the heart of autonomous execution. It runs in the background and:
|
|
140
142
|
|
|
141
|
-
|
|
143
|
+
- Picks up pending tasks from the queue
|
|
144
|
+
- Runs **up to 3 tasks in parallel** (independent tasks only)
|
|
145
|
+
- **Chains outputs** โ downstream tasks get results from their dependencies
|
|
146
|
+
- **Re-plans on failure** โ uses LLM to suggest alternative approaches
|
|
147
|
+
- Loads **all project capabilities** โ skills, scripts, commands, plugins, credentials
|
|
142
148
|
|
|
143
149
|
```bash
|
|
144
|
-
#
|
|
145
|
-
agent
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
# Install a skill
|
|
151
|
-
agent skills install <skill-name>
|
|
150
|
+
agent daemon start # Start background processing
|
|
151
|
+
agent daemon status # Check health & progress
|
|
152
|
+
agent daemon logs # View execution log
|
|
153
|
+
agent daemon stop # Graceful shutdown
|
|
154
|
+
```
|
|
152
155
|
|
|
153
|
-
|
|
154
|
-
agent skills create my-new-skill
|
|
155
|
-
# โ Creates .agent/skills/my-new-skill/prompt.md
|
|
156
|
+
### Example Daemon Log
|
|
156
157
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
158
|
+
```
|
|
159
|
+
๐ง Auto-decomposing goal #1: "Build data pipeline for GitHub API"
|
|
160
|
+
โ
Created 5 subtask(s)
|
|
161
|
+
๐ Processing task #1: "Fetch trending repos"
|
|
162
|
+
๐ฆ Loaded: 2 skills, 3 commands, 6 scripts, 1 plugin, 8 credentials
|
|
163
|
+
โ
Task #1 completed
|
|
164
|
+
๐ Processing task #2: "Transform JSON response" [parallel: 2]
|
|
165
|
+
๐ Processing task #3: "Save to file" [parallel: 3]
|
|
166
|
+
โ
Task #2 completed
|
|
167
|
+
โ
Task #3 completed
|
|
168
|
+
๐ Processing task #4: "Create re-run script"
|
|
169
|
+
โ
Task #4 completed โ Goal 100% complete
|
|
161
170
|
```
|
|
162
171
|
|
|
163
172
|
---
|
|
164
173
|
|
|
165
|
-
|
|
174
|
+
## ๐ Credential Vault
|
|
166
175
|
|
|
167
|
-
|
|
176
|
+
The agent has a built-in **encrypted credential store** so it can use API keys, tokens, and passwords securely.
|
|
168
177
|
|
|
169
|
-
|
|
178
|
+
### How It Works
|
|
170
179
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
description: Deploy current branch to staging
|
|
175
|
-
tools: [cmd.run, git.status, git.diff]
|
|
176
|
-
---
|
|
177
|
-
# Deploy to Staging
|
|
180
|
+
1. **Vault** โ Secrets stored in `.agent/vault.json`, encrypted with AES-256-GCM
|
|
181
|
+
2. **`.env` fallback** โ Credentials from `.env` are auto-detected
|
|
182
|
+
3. **Interactive capture** โ If the agent needs a credential it doesn't have, it asks you via Studio
|
|
178
183
|
|
|
179
|
-
|
|
180
|
-
1. Run `npm test` to verify all tests pass
|
|
181
|
-
2. Run `npm run build` to create the production bundle
|
|
182
|
-
3. Run `git push origin HEAD:staging` to trigger deployment
|
|
183
|
-
```
|
|
184
|
+
### Adding Credentials
|
|
184
185
|
|
|
185
|
-
|
|
186
|
+
**Via Studio UI:**
|
|
187
|
+
1. Open Agent Studio โ Credentials
|
|
188
|
+
2. Click "Add Secret"
|
|
189
|
+
3. Enter key name (e.g., `GITHUB_TOKEN`) and value
|
|
190
|
+
4. Stored encrypted on disk
|
|
186
191
|
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
192
|
+
**Via `.env` file:**
|
|
193
|
+
```env
|
|
194
|
+
GITHUB_TOKEN=ghp_xxxx
|
|
195
|
+
OPENAI_API_KEY=sk-xxxx
|
|
196
|
+
APIFY_TOKEN=apify_api_xxxx
|
|
191
197
|
```
|
|
192
198
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
```bash
|
|
196
|
-
agent commands list # See all available commands
|
|
197
|
-
```
|
|
199
|
+
**Via CLI tools:**
|
|
200
|
+
The LLM uses `secrets.get({ key: "GITHUB_TOKEN" })` to retrieve credentials during task execution. It never hardcodes them.
|
|
198
201
|
|
|
199
202
|
---
|
|
200
203
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
Scripts are repeatable, scriptable tasks (shell/Node Python) defined via a `script.yaml` manifest. They differ from Skills and Commands because they execute directly without LLM involvement, making them perfect for CI/CD tasks, builds, or deployments.
|
|
204
|
+
## ๐ Agent Studio (Web Dashboard)
|
|
204
205
|
|
|
205
|
-
|
|
206
|
+
A full web-based management console for your agent:
|
|
206
207
|
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
entrypoint: deploy.sh
|
|
211
|
-
confirm: true
|
|
212
|
-
args:
|
|
213
|
-
branch:
|
|
214
|
-
description: Branch to deploy
|
|
215
|
-
default: main
|
|
208
|
+
```bash
|
|
209
|
+
agent studio
|
|
210
|
+
# โ Agent Studio running at http://localhost:3333
|
|
216
211
|
```
|
|
217
212
|
|
|
218
|
-
|
|
213
|
+
### Pages
|
|
214
|
+
|
|
215
|
+
| Page | What It Shows |
|
|
216
|
+
|------|--------------|
|
|
217
|
+
| **Console** | Real-time terminal with live command relay |
|
|
218
|
+
| **Capabilities** | Loaded tools, permissions, provider info |
|
|
219
|
+
| **Goals & Tasks** | Create goals, track progress, view task status |
|
|
220
|
+
| **Templates** | Pre-built goal templates (blog writer, data pipeline, etc.) |
|
|
221
|
+
| **Credentials** | Encrypted vault โ add/delete API keys and tokens |
|
|
222
|
+
| **Skills** | Installed skills with success metrics |
|
|
223
|
+
| **Commands** | Lightweight automation templates |
|
|
224
|
+
| **Scripts** | Project scripts with execution and output viewer |
|
|
225
|
+
| **Plugins** | Installed plugin bundles |
|
|
226
|
+
| **Daemon** | Start/stop daemon, view logs, health status |
|
|
227
|
+
| **Memory** | Search and browse persistent agent memory |
|
|
228
|
+
|
|
229
|
+
### Goal Templates
|
|
230
|
+
|
|
231
|
+
Studio includes **6 pre-built goal templates** for common workflows:
|
|
232
|
+
|
|
233
|
+
- ๐ **System Health Monitor** โ Dashboard with CPU/memory/disk monitoring
|
|
234
|
+
- โ๏ธ **Blog Post Writer** โ Research + write + SEO optimization
|
|
235
|
+
- ๐ท๏ธ **Apify Actor Creator** โ Scaffold a web scraping actor
|
|
236
|
+
- ๐ **Code Review & Refactor** โ Analyze and improve code quality
|
|
237
|
+
- ๐ **Data Pipeline** โ Fetch โ transform โ save with error handling
|
|
238
|
+
- ๐
**Recurring Report** โ Automated daily/weekly reports
|
|
219
239
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## ๐ ๏ธ Extensibility
|
|
243
|
+
|
|
244
|
+
### Skills
|
|
225
245
|
|
|
226
|
-
|
|
246
|
+
Reusable AI capabilities defined by a `skill.json` manifest + `prompt.md`:
|
|
227
247
|
|
|
228
248
|
```bash
|
|
229
|
-
agent
|
|
230
|
-
#
|
|
231
|
-
|
|
232
|
-
|
|
249
|
+
agent skills list # List installed skills
|
|
250
|
+
agent skills create my-skill # Create a custom skill
|
|
251
|
+
agent skills stats # View success metrics
|
|
252
|
+
agent skills fix my-skill # Auto-repair with LLM
|
|
233
253
|
```
|
|
234
254
|
|
|
235
|
-
|
|
255
|
+
**Example:** Create `.agent/skills/deploy/skill.json` + `prompt.md` โ the agent uses it whenever a deployment goal comes up.
|
|
236
256
|
|
|
237
|
-
|
|
257
|
+
### Commands
|
|
238
258
|
|
|
239
|
-
|
|
259
|
+
Lightweight goal templates โ just a markdown file with YAML frontmatter:
|
|
240
260
|
|
|
241
|
-
|
|
261
|
+
```markdown
|
|
262
|
+
---
|
|
263
|
+
name: deploy-staging
|
|
264
|
+
description: Deploy current branch to staging
|
|
265
|
+
tools: [cmd.run, git.status]
|
|
266
|
+
---
|
|
267
|
+
# Deploy to Staging
|
|
268
|
+
1. Run `npm test` to verify all tests pass
|
|
269
|
+
2. Run `npm run build`
|
|
270
|
+
3. Push to staging branch
|
|
271
|
+
```
|
|
242
272
|
|
|
243
|
-
```
|
|
244
|
-
|
|
245
|
-
"hooks": {
|
|
246
|
-
"after:tool": [
|
|
247
|
-
{
|
|
248
|
-
"match": "fs.write",
|
|
249
|
-
"command": "npx prettier --write {{path}}",
|
|
250
|
-
"blocking": false
|
|
251
|
-
}
|
|
252
|
-
],
|
|
253
|
-
"before:plan": [
|
|
254
|
-
{
|
|
255
|
-
"command": "./scripts/validate-env.sh",
|
|
256
|
-
"blocking": true
|
|
257
|
-
}
|
|
258
|
-
]
|
|
259
|
-
}
|
|
260
|
-
}
|
|
273
|
+
```bash
|
|
274
|
+
> /deploy-staging # Use from interactive mode
|
|
261
275
|
```
|
|
262
276
|
|
|
263
|
-
|
|
277
|
+
### Scripts
|
|
264
278
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
279
|
+
Direct automation (no LLM needed) โ shell, Python, or Node.js:
|
|
280
|
+
|
|
281
|
+
```yaml
|
|
282
|
+
# .agent/scripts/deploy/script.yaml
|
|
283
|
+
name: deploy-staging
|
|
284
|
+
description: Build and deploy to staging
|
|
285
|
+
entrypoint: run.sh
|
|
286
|
+
```
|
|
273
287
|
|
|
274
288
|
```bash
|
|
275
|
-
agent
|
|
276
|
-
agent hooks add after:tool "npx eslint --fix {{path}}" --match fs.write
|
|
277
|
-
agent hooks events # Show all available events
|
|
289
|
+
agent scripts run deploy-staging
|
|
278
290
|
```
|
|
279
291
|
|
|
280
|
-
|
|
292
|
+
The daemon auto-discovers scripts and can execute them via the `script.run` tool.
|
|
281
293
|
|
|
282
|
-
###
|
|
294
|
+
### Plugins
|
|
283
295
|
|
|
284
|
-
Bundle skills
|
|
296
|
+
Bundle skills + commands + scripts + hooks into a package:
|
|
285
297
|
|
|
286
298
|
```
|
|
287
299
|
my-plugin/
|
|
288
300
|
โโโ plugin.json
|
|
289
301
|
โโโ skills/
|
|
290
|
-
โ โโโ security-scan/
|
|
291
|
-
โ โโโ skill.json
|
|
292
|
-
โ โโโ prompt.md
|
|
293
302
|
โโโ commands/
|
|
294
|
-
|
|
303
|
+
โโโ scripts/
|
|
295
304
|
โโโ hooks/
|
|
296
|
-
โโโ hooks.json
|
|
297
|
-
```
|
|
298
|
-
|
|
299
|
-
`plugin.json`:
|
|
300
|
-
```json
|
|
301
|
-
{
|
|
302
|
-
"name": "enterprise-security",
|
|
303
|
-
"version": "1.0.0",
|
|
304
|
-
"description": "Security scanning and compliance",
|
|
305
|
-
"skills": ["skills/"],
|
|
306
|
-
"commands": ["commands/"],
|
|
307
|
-
"scripts": ["scripts/"],
|
|
308
|
-
"hooks": "hooks/hooks.json"
|
|
309
|
-
}
|
|
310
305
|
```
|
|
311
306
|
|
|
312
307
|
```bash
|
|
313
|
-
agent plugins install ./my-plugin
|
|
314
|
-
agent plugins list
|
|
315
|
-
agent plugins remove my-plugin # Uninstall
|
|
308
|
+
agent plugins install ./my-plugin
|
|
309
|
+
agent plugins list
|
|
316
310
|
```
|
|
317
311
|
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
### 7. Multi-CLI Orchestration
|
|
321
|
-
|
|
322
|
-
The agent can delegate tasks to external AI CLIs when they're the right tool for the job:
|
|
312
|
+
### Lifecycle Hooks
|
|
323
313
|
|
|
324
|
-
|
|
325
|
-
|------|-----|----------|
|
|
326
|
-
| `cli.cursor` | Cursor | Multi-file refactoring with codebase context |
|
|
327
|
-
| `cli.codex` | OpenAI Codex | Code generation with sandbox execution |
|
|
328
|
-
| `cli.gemini` | Gemini | Large-context analysis and reasoning |
|
|
329
|
-
| `cli.claude` | Claude | Careful code review and generation |
|
|
314
|
+
Intercept execution at 10 event points:
|
|
330
315
|
|
|
331
|
-
Configure in `.agent/config.json`:
|
|
332
316
|
```json
|
|
333
317
|
{
|
|
334
|
-
"
|
|
335
|
-
"
|
|
336
|
-
|
|
318
|
+
"hooks": {
|
|
319
|
+
"after:tool": [{
|
|
320
|
+
"match": "fs.write",
|
|
321
|
+
"command": "npx prettier --write {{path}}"
|
|
322
|
+
}]
|
|
337
323
|
}
|
|
338
324
|
}
|
|
339
325
|
```
|
|
340
326
|
|
|
341
|
-
The LLM orchestrator automatically selects the right CLI based on the task.
|
|
342
|
-
|
|
343
327
|
---
|
|
344
328
|
|
|
345
|
-
|
|
329
|
+
## ๐ค Interactive Mode
|
|
346
330
|
|
|
347
|
-
|
|
331
|
+
The conversational REPL with multi-turn context:
|
|
348
332
|
|
|
349
333
|
```bash
|
|
350
|
-
|
|
351
|
-
agent goal add "Build authentication with OAuth2" --priority 1
|
|
334
|
+
agent
|
|
352
335
|
|
|
353
|
-
|
|
354
|
-
|
|
336
|
+
> Add rate limiting to the /api/auth endpoint
|
|
337
|
+
โก fs.read(src/routes/auth.ts) โ
|
|
338
|
+
โก fs.write(src/middleware/rateLimit.ts) โ
|
|
339
|
+
โ Done
|
|
355
340
|
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
agent goal list # See goal status
|
|
361
|
-
agent goal status 1 # Detailed task view
|
|
362
|
-
agent daemon status # Daemon health
|
|
363
|
-
agent daemon logs # Recent execution logs
|
|
341
|
+
> Now write tests for it
|
|
342
|
+
โก fs.write(src/__tests__/rateLimit.test.ts) โ
|
|
343
|
+
โก cmd.run(npm test) โ
|
|
344
|
+
โ All 5 tests passing
|
|
364
345
|
|
|
365
|
-
|
|
366
|
-
|
|
346
|
+
> /deploy-staging
|
|
347
|
+
Running command: deploy-staging...
|
|
367
348
|
```
|
|
368
349
|
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
### 9. Plans
|
|
372
|
-
|
|
373
|
-
Create and run structured execution plans:
|
|
350
|
+
### Slash Commands
|
|
374
351
|
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
352
|
+
| Command | Action |
|
|
353
|
+
|---------|--------|
|
|
354
|
+
| `/help` | Show all available commands |
|
|
355
|
+
| `/skills` | List installed skills |
|
|
356
|
+
| `/commands` | List available commands |
|
|
357
|
+
| `/scripts` | List available scripts |
|
|
358
|
+
| `/model` | Display LLM provider info |
|
|
359
|
+
| `/compact` | Summarize and free context |
|
|
380
360
|
|
|
381
361
|
---
|
|
382
362
|
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
The agent stores facts, learnings, and project context persistently:
|
|
363
|
+
## ๐๏ธ Architecture
|
|
386
364
|
|
|
387
|
-
```bash
|
|
388
|
-
agent memory search "database credentials"
|
|
389
|
-
agent memory add "Staging server is at 10.0.0.5" --category fact
|
|
390
365
|
```
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
366
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
367
|
+
โ CLI / REPL / Studio โ
|
|
368
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
|
|
369
|
+
โ LLM Router โ
|
|
370
|
+
โ OpenAI โ Anthropic โ Azure โ Ollama (fallback chain) โ
|
|
371
|
+
โโโโโโโโโโโโฌโโโโโโโโโโโฌโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโค
|
|
372
|
+
โ Skills โ Commands โ Scripts โ Plugins โ
|
|
373
|
+
โ prompt โ .md โ .yaml โ bundles โ
|
|
374
|
+
โโโโโโโโโโโโดโโโโโโโโโโโดโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโค
|
|
375
|
+
โ Tool Registry & Policy Engine โ
|
|
376
|
+
โ fs.* โ cmd.run โ git.* โ http.* โ secrets.* โ script.* โ
|
|
377
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
|
|
378
|
+
โ Goal Decomposer โ Daemon โ Credential Vault โ Memory โ
|
|
379
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
401
380
|
```
|
|
402
381
|
|
|
403
|
-
|
|
382
|
+
### Key Components
|
|
404
383
|
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
384
|
+
| Component | Purpose |
|
|
385
|
+
|-----------|---------|
|
|
386
|
+
| **LLM Router** | Multi-provider routing with fallback chains (OpenAI โ Anthropic โ Ollama) |
|
|
387
|
+
| **Goal Decomposer** | LLM-powered breakdown of goals into dependency-aware task graphs |
|
|
388
|
+
| **Daemon Service** | Background task runner with parallel execution, retries, re-planning |
|
|
389
|
+
| **Credential Vault** | AES-256-GCM encrypted secret storage with `.env` fallback |
|
|
390
|
+
| **Tool Registry** | Sandboxed execution with permission gates |
|
|
391
|
+
| **Policy Engine** | Human-in-the-loop approval for sensitive operations |
|
|
392
|
+
| **Memory Store** | SQLite + FTS5 persistent memory across sessions |
|
|
393
|
+
| **Plugin Loader** | Discovers and loads sub-packages of skills, commands, scripts, hooks |
|
|
417
394
|
|
|
418
395
|
---
|
|
419
396
|
|
|
420
|
-
|
|
397
|
+
## โ๏ธ Configuration
|
|
421
398
|
|
|
422
|
-
|
|
399
|
+
### `agent.yaml` (or `.agent/config.json`)
|
|
423
400
|
|
|
424
|
-
```
|
|
425
|
-
|
|
426
|
-
|
|
401
|
+
```yaml
|
|
402
|
+
llm:
|
|
403
|
+
provider: openai # openai | anthropic | azure | ollama
|
|
404
|
+
model: gpt-4o
|
|
405
|
+
fallback:
|
|
406
|
+
- provider: anthropic
|
|
407
|
+
model: claude-3-sonnet
|
|
408
|
+
|
|
409
|
+
daemon:
|
|
410
|
+
maxConcurrent: 3 # Parallel task limit
|
|
411
|
+
|
|
412
|
+
policy:
|
|
413
|
+
permissions:
|
|
414
|
+
- "*" # Wildcard for full autonomy
|
|
427
415
|
```
|
|
428
416
|
|
|
429
|
-
|
|
430
|
-
and installs updates in the background without blocking your session.
|
|
431
|
-
|
|
432
|
-
---
|
|
417
|
+
### LLM Providers
|
|
433
418
|
|
|
434
|
-
|
|
419
|
+
| Provider | Env Variable | Models |
|
|
420
|
+
|----------|-------------|--------|
|
|
421
|
+
| OpenAI | `OPENAI_API_KEY` | gpt-4o, gpt-4o-mini |
|
|
422
|
+
| Anthropic | `ANTHROPIC_API_KEY` | claude-3-sonnet, claude-3-opus |
|
|
423
|
+
| Azure OpenAI | `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT` | Any deployed model |
|
|
424
|
+
| Ollama | None (local) | llama3, codellama, mistral |
|
|
435
425
|
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
| Command | Description |
|
|
439
|
-
|---------|-------------|
|
|
440
|
-
| `agent` | Launch interactive REPL (no subcommand) |
|
|
441
|
-
| `agent run "<goal>"` | One-shot goal execution |
|
|
442
|
-
| `agent init` | Initialize project configuration |
|
|
443
|
-
| `agent config --init` | Set up global config |
|
|
444
|
-
| `agent doctor` | System health check |
|
|
445
|
-
| `agent update` | Update CLI to latest version |
|
|
446
|
-
| `agent studio` | Launch web-based management console |
|
|
426
|
+
---
|
|
447
427
|
|
|
448
|
-
|
|
428
|
+
## ๐ Full CLI Reference
|
|
449
429
|
|
|
450
|
-
|
|
451
|
-
|---------|-------------|
|
|
452
|
-
| `agent skills list` | List installed skills |
|
|
453
|
-
| `agent skills search <query>` | Search the skill hub |
|
|
454
|
-
| `agent skills install <name>` | Install a skill |
|
|
455
|
-
| `agent skills create <name>` | Create a custom skill |
|
|
456
|
-
| `agent skills stats` | View performance metrics |
|
|
457
|
-
| `agent skills doctor <name>` | Diagnose a failing skill |
|
|
458
|
-
| `agent skills fix <name>` | Auto-repair with LLM |
|
|
430
|
+
### Core Commands
|
|
459
431
|
|
|
460
|
-
|
|
432
|
+
```bash
|
|
433
|
+
agent # Interactive REPL
|
|
434
|
+
agent run "<goal>" # One-shot goal execution
|
|
435
|
+
agent init # Initialize project
|
|
436
|
+
agent studio # Web dashboard at :3333
|
|
437
|
+
agent doctor # System health check
|
|
438
|
+
agent update # Update to latest version
|
|
439
|
+
```
|
|
461
440
|
|
|
462
|
-
|
|
463
|
-
|---------|-------------|
|
|
464
|
-
| `agent commands list` | List available commands |
|
|
441
|
+
### Goal & Daemon
|
|
465
442
|
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
443
|
+
```bash
|
|
444
|
+
agent goal add "<title>" # Create a goal
|
|
445
|
+
agent goal list # List all goals
|
|
446
|
+
agent goal decompose <id> # AI breakdown into tasks
|
|
447
|
+
agent goal status <id> # Task-level progress
|
|
448
|
+
|
|
449
|
+
agent daemon start # Start background worker
|
|
450
|
+
agent daemon stop # Stop gracefully
|
|
451
|
+
agent daemon status # Health & uptime
|
|
452
|
+
agent daemon logs # Recent execution logs
|
|
453
|
+
```
|
|
473
454
|
|
|
474
|
-
###
|
|
455
|
+
### Skills, Commands, Scripts, Plugins
|
|
475
456
|
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
457
|
+
```bash
|
|
458
|
+
agent skills list | create | stats | fix
|
|
459
|
+
agent commands list
|
|
460
|
+
agent scripts list | run <name> | show <name>
|
|
461
|
+
agent plugins list | install <path> | remove <name>
|
|
462
|
+
agent hooks list | add <event> <cmd>
|
|
463
|
+
```
|
|
481
464
|
|
|
482
|
-
###
|
|
465
|
+
### Memory & Reports
|
|
483
466
|
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
### Goals & Daemon
|
|
491
|
-
|
|
492
|
-
| Command | Description |
|
|
493
|
-
|---------|-------------|
|
|
494
|
-
| `agent goal add "<title>"` | Create a goal |
|
|
495
|
-
| `agent goal list` | List goals |
|
|
496
|
-
| `agent goal decompose <id>` | AI breakdown |
|
|
497
|
-
| `agent goal status <id>` | Task-level progress |
|
|
498
|
-
| `agent daemon start` | Start background worker |
|
|
499
|
-
| `agent daemon stop` | Stop background worker |
|
|
500
|
-
| `agent daemon status` | Health & uptime |
|
|
501
|
-
|
|
502
|
-
### Plans, Memory & Reports
|
|
503
|
-
|
|
504
|
-
| Command | Description |
|
|
505
|
-
|---------|-------------|
|
|
506
|
-
| `agent plan propose "<desc>"` | AI-generate a plan |
|
|
507
|
-
| `agent plan run <file>` | Execute a plan |
|
|
508
|
-
| `agent memory search <query>` | Search agent memory |
|
|
509
|
-
| `agent memory add "<fact>"` | Store a fact |
|
|
510
|
-
| `agent report generate` | Activity report |
|
|
467
|
+
```bash
|
|
468
|
+
agent memory search "<query>" # Semantic search
|
|
469
|
+
agent memory add "<fact>" # Store a fact
|
|
470
|
+
agent report generate # Activity summary
|
|
471
|
+
```
|
|
511
472
|
|
|
512
473
|
---
|
|
513
474
|
|
|
514
|
-
##
|
|
475
|
+
## ๐ Project Structure
|
|
476
|
+
|
|
477
|
+
After `agent init`, your project contains:
|
|
515
478
|
|
|
516
479
|
```
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
โ
|
|
520
|
-
|
|
521
|
-
โ
|
|
522
|
-
โ
|
|
523
|
-
|
|
524
|
-
โ
|
|
525
|
-
โ
|
|
526
|
-
|
|
527
|
-
โ
|
|
528
|
-
โ
|
|
529
|
-
|
|
530
|
-
โ
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
- **Commands**: Lightweight goal templates (YAML frontmatter + prompt)
|
|
539
|
-
- **Scripts**: Direct executable automation with argument injection
|
|
540
|
-
- **Hooks**: Event-driven lifecycle interception
|
|
541
|
-
- **Plugins**: Distributable bundles of skills + commands + scripts + hooks
|
|
542
|
-
- **Tool Registry**: Sandboxed tool execution with permission gates
|
|
543
|
-
- **Policy Engine**: Human-in-the-loop approval for sensitive operations
|
|
544
|
-
- **Multi-CLI Tools**: Cursor, Codex, Gemini, Claude wrappers
|
|
480
|
+
your-project/
|
|
481
|
+
โโโ .agent/
|
|
482
|
+
โ โโโ config.json # Agent configuration
|
|
483
|
+
โ โโโ vault.json # Encrypted credentials (auto-created)
|
|
484
|
+
โ โโโ memory.db # SQLite persistent memory
|
|
485
|
+
โ โโโ daemon.log # Daemon execution log
|
|
486
|
+
โ โโโ skills/ # Custom skills
|
|
487
|
+
โ โ โโโ my-skill/
|
|
488
|
+
โ โ โโโ skill.json
|
|
489
|
+
โ โ โโโ prompt.md
|
|
490
|
+
โ โโโ commands/ # Lightweight commands
|
|
491
|
+
โ โ โโโ deploy.md
|
|
492
|
+
โ โโโ scripts/ # Automation scripts
|
|
493
|
+
โ โ โโโ health-check/
|
|
494
|
+
โ โ โโโ script.yaml
|
|
495
|
+
โ โ โโโ run.sh
|
|
496
|
+
โ โโโ plugins/ # Installed plugins
|
|
497
|
+
โ โโโ hooks/
|
|
498
|
+
โ โโโ hooks.json # Lifecycle hooks
|
|
499
|
+
โโโ .env # Environment variables (auto-detected)
|
|
500
|
+
```
|
|
545
501
|
|
|
546
502
|
---
|
|
547
503
|
|
|
548
|
-
##
|
|
549
|
-
|
|
550
|
-
Understand the agent architecture with our 12-part deep-dive:
|
|
551
|
-
|
|
552
|
-
1. [**Vision & Architecture**](docs/articles/01-vision-architecture.md) โ The high-level design
|
|
553
|
-
2. [**The Brain (Planner)**](docs/articles/02-goal-decomposition.md) โ Goal decomposition
|
|
554
|
-
3. [**The Body (Executor)**](docs/articles/03-skill-execution.md) โ Secure skill execution
|
|
555
|
-
4. [**Memory & Context**](docs/articles/04-memory-persistence.md) โ SQLite & semantic search
|
|
556
|
-
5. [**Self-Improvement**](docs/articles/05-self-improvement.md) โ Metrics & the Auto-Fixer
|
|
557
|
-
6. [**Plugin Ecosystem**](docs/articles/06-plugin-ecosystem.md) โ Hooks, commands, multi-CLI
|
|
558
|
-
7. [**Interactive CLI**](docs/articles/07-interactive-cli.md) โ The conversational experience
|
|
559
|
-
8. [**Scripts System**](docs/articles/08-scripts-system.md) โ Non-LLM deterministic automation
|
|
560
|
-
9. [**Agent Studio**](docs/articles/09-agent-studio.md) โ Web management console
|
|
561
|
-
10. [**LLM Providers**](docs/articles/10-llm-providers.md) โ Provider configuration & routing
|
|
562
|
-
11. [**Policy & Approvals**](docs/articles/11-policy-approvals.md) โ Permission-gated execution
|
|
563
|
-
12. [**Daemon & Automation**](docs/articles/12-daemon-automation.md) โ Background task processing
|
|
564
|
-
|
|
565
|
-
### Reference
|
|
566
|
-
- [**REST API Reference**](docs/API.md) โ Complete Studio API docs
|
|
567
|
-
- [**Configuration Reference**](docs/CONFIGURATION.md) โ All config options
|
|
504
|
+
## ๐ Security
|
|
568
505
|
|
|
569
|
-
|
|
570
|
-
-
|
|
506
|
+
- **Credential encryption** โ AES-256-GCM with machine-specific keys
|
|
507
|
+
- **Permission gating** โ Policy engine controls which tools can execute
|
|
508
|
+
- **Human-in-the-loop** โ Tasks can require manual approval before executing
|
|
509
|
+
- **No credential leaking** โ Secrets are never logged or included in LLM prompts as raw values
|
|
510
|
+
- **Sandboxed execution** โ Tools execute within the project directory scope
|
|
571
511
|
|
|
572
512
|
---
|
|
573
513
|
|
|
574
|
-
##
|
|
514
|
+
## ๐ What's New in v0.9.25
|
|
575
515
|
|
|
576
|
-
|
|
577
|
-
-
|
|
578
|
-
-
|
|
579
|
-
-
|
|
580
|
-
-
|
|
581
|
-
-
|
|
582
|
-
-
|
|
516
|
+
- **โก Parallel Task Execution** โ Up to 3 tasks run simultaneously
|
|
517
|
+
- **๐ Task Output Chaining** โ Downstream tasks receive upstream results
|
|
518
|
+
- **๐ Dynamic Re-decomposition** โ Failed tasks trigger LLM re-planning
|
|
519
|
+
- **๐ Credential Vault** โ Encrypted secret storage with Studio UI
|
|
520
|
+
- **๐ HTTP Tool** โ `http.request` for API integrations
|
|
521
|
+
- **๐ฆ Full Capability Loading** โ Daemon uses all project skills, scripts, commands, plugins
|
|
522
|
+
- **๐ Goal Templates** โ 6 pre-built workflow templates in Studio
|
|
523
|
+
- **๐ Script & Command Tools** โ LLM can execute existing scripts and commands
|
|
583
524
|
|
|
584
525
|
---
|
|
585
526
|
|
|
586
527
|
## ๐ค Contributing
|
|
587
528
|
|
|
588
|
-
We welcome contributions!
|
|
529
|
+
We welcome contributions! Key areas:
|
|
589
530
|
|
|
590
|
-
|
|
591
|
-
-
|
|
592
|
-
-
|
|
593
|
-
- Building the Web Dashboard
|
|
531
|
+
- Writing new Skills and Commands
|
|
532
|
+
- Improving LLM prompt engineering
|
|
533
|
+
- Building Studio UI components
|
|
594
534
|
- Creating community Plugins
|
|
535
|
+
- Writing documentation
|
|
595
536
|
|
|
596
537
|
---
|
|
597
538
|
|