@agentic-patterns/cli 0.1.0 → 0.1.2
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 +117 -0
- package/assets/dashboard/assets/{index-Bv9u9q_K.js → index-C2JvJdBt.js} +29 -29
- package/assets/dashboard/index.html +1 -1
- package/package.json +14 -14
- package/LICENSE +0 -21
package/README.md
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# @agentic-patterns/cli
|
|
2
|
+
|
|
3
|
+
`ap` — the command-line entry point for agentic-patterns. Discovers agents in a project, wires runners + event bus, and launches a Hono server with an admin dashboard SPA.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
bun add -g @agentic-patterns/cli
|
|
9
|
+
# or
|
|
10
|
+
npm install -g @agentic-patterns/cli
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Or use without installing:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npx @agentic-patterns/cli <command>
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Quick Start
|
|
20
|
+
|
|
21
|
+
Scaffold a new project from scratch:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
ap init my-agents --provider=anthropic --with-plugin
|
|
25
|
+
cd my-agents
|
|
26
|
+
cp .env.example .env # add ANTHROPIC_API_KEY
|
|
27
|
+
bun install
|
|
28
|
+
bun run dev
|
|
29
|
+
# → http://localhost:3000
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The `--with-plugin` flag drops a Claude Code plugin (`.claude-plugin/` + `hooks/`) next to your project — any Claude Code session in that directory streams lifecycle events into your dashboard in real time.
|
|
33
|
+
|
|
34
|
+
## Commands
|
|
35
|
+
|
|
36
|
+
| Command | Purpose |
|
|
37
|
+
|---|---|
|
|
38
|
+
| `ap` | Bare call — status dashboard showing discovered agents, env detection |
|
|
39
|
+
| `ap init [<dir>]` | Scaffold a new agent project |
|
|
40
|
+
| `ap agents` | List all discovered agents in the current project |
|
|
41
|
+
| `ap run <agent> [message]` | Chat with an agent in the terminal — interactive or one-shot |
|
|
42
|
+
| `ap playground` | Launch server + dashboard (production mode: SPA mounted at `/`) |
|
|
43
|
+
| `ap config` | Show env detection status (which provider keys are present) |
|
|
44
|
+
| `ap config set` | Interactive `.env` editor |
|
|
45
|
+
|
|
46
|
+
### `ap init [<dir>]`
|
|
47
|
+
|
|
48
|
+
Scaffolds `package.json`, `.env.example`, `tsconfig.json`, and a working `agents/demo/agent.ts`.
|
|
49
|
+
|
|
50
|
+
Flags:
|
|
51
|
+
- `--provider=<p>` — `anthropic` | `openai` | `ollama` (sets the SDK dep + env key)
|
|
52
|
+
- `--with-plugin` — also drop `.claude-plugin/` + `hooks/` for Claude Code integration
|
|
53
|
+
- `--link` — scaffold into the local monorepo's `examples/` directory using `workspace:*` deps (dogfooding only, pre-publish)
|
|
54
|
+
|
|
55
|
+
### `ap playground`
|
|
56
|
+
|
|
57
|
+
Starts a self-contained server + dashboard:
|
|
58
|
+
- Hono HTTP routes on port 3000 (override with `--port`)
|
|
59
|
+
- Dashboard SPA mounted at `/` (skip with `--no-dashboard`)
|
|
60
|
+
- Auto-opens the browser (skip with `--no-open`)
|
|
61
|
+
- Wires `AgentEventBus` + `SSEExporter` so every agent interaction streams to the dashboard's `/admin/events/stream` endpoint
|
|
62
|
+
|
|
63
|
+
### `ap run <agent> [message]`
|
|
64
|
+
|
|
65
|
+
Terminal chat:
|
|
66
|
+
- With a message: one-shot, prints the response and exits
|
|
67
|
+
- Without: interactive REPL
|
|
68
|
+
|
|
69
|
+
## Agent Discovery
|
|
70
|
+
|
|
71
|
+
The CLI walks `agents/**/agent.ts` (or `agents/**/*.agent.ts`) from your project root. Each file must default-export an `AgentRegistration`:
|
|
72
|
+
|
|
73
|
+
```typescript
|
|
74
|
+
// agents/demo/agent.ts
|
|
75
|
+
import { AgentBuilder, RoleBuilder, Persona, Mission } from "@agentic-patterns/core";
|
|
76
|
+
|
|
77
|
+
const role = new RoleBuilder("demo")
|
|
78
|
+
.withPersona(new Persona({ identity: "a demo assistant", tone: "concise" }))
|
|
79
|
+
.build();
|
|
80
|
+
|
|
81
|
+
const agent = new AgentBuilder(role)
|
|
82
|
+
.withMission(new Mission({ objective: "Demonstrate the framework" }))
|
|
83
|
+
.build();
|
|
84
|
+
|
|
85
|
+
export default {
|
|
86
|
+
id: "demo",
|
|
87
|
+
name: "Demo",
|
|
88
|
+
description: "A simple demo agent",
|
|
89
|
+
agent,
|
|
90
|
+
};
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The CLI injects the runner from your environment — you don't construct one yourself.
|
|
94
|
+
|
|
95
|
+
Override the discovery glob: `ap --agents "src/bots/*/index.ts" playground`
|
|
96
|
+
|
|
97
|
+
## Environment Detection
|
|
98
|
+
|
|
99
|
+
`ap` reads `.env` (via dotenv) from your project root. It auto-detects provider credentials:
|
|
100
|
+
- `ANTHROPIC_API_KEY` → Anthropic runner
|
|
101
|
+
- `OPENAI_API_KEY` → OpenAI runner
|
|
102
|
+
- `OLLAMA_HOST` → local Ollama
|
|
103
|
+
- `AP_DASHBOARD_URL` → where the Claude Code plugin POSTs hooks (default `http://localhost:3000`)
|
|
104
|
+
|
|
105
|
+
Run `ap config` to verify detection. Run `ap config set` for an interactive editor.
|
|
106
|
+
|
|
107
|
+
## Claude Code Plugin
|
|
108
|
+
|
|
109
|
+
When scaffolded with `--with-plugin`, the plugin wires all 26 Claude Code lifecycle events to a local `hooks/emit.mjs` that POSTs to `${AP_DASHBOARD_URL}/hooks/:eventType`. The server publishes them to the event bus; the dashboard's `/claude-code` page renders them grouped by session.
|
|
110
|
+
|
|
111
|
+
This means any Claude Code session in a project with the plugin enabled becomes live-observable in your dashboard — tool calls, permission prompts, subagent spawns, compaction, everything.
|
|
112
|
+
|
|
113
|
+
See the [plugin docs](../../.claude-plugin/plugin.json) for details.
|
|
114
|
+
|
|
115
|
+
## License
|
|
116
|
+
|
|
117
|
+
MIT
|