Skip to content

Commit c2dd07e

Browse files
OneStepAt4timeOneStepAt4time
authored
docs: add session export user guide + competitive threat matrix
PR #3161 — approved by aegis-gh-agent[bot] (Argus)
1 parent bf38896 commit c2dd07e

3 files changed

Lines changed: 219 additions & 2 deletions

File tree

‎docs/advanced.md‎

Lines changed: 115 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Advanced Features
22

3-
Aegis provides orchestration primitives beyond basic session management. This guide covers the Memory Bridge, Model Router, Session Templates, Verification Protocol, and Diagnostics.
3+
Aegis provides orchestration primitives beyond basic session management. This guide covers the Memory Bridge, Session Export, Session Templates, Verification Protocol, Pipeline Orchestration, and Diagnostics.
44

55
For OpenAI-compatible model routing via Claude Code (`ANTHROPIC_BASE_URL` + custom models), see [BYO LLM](./byo-llm.md).
66

@@ -155,6 +155,120 @@ curl -X POST http://localhost:9100/v1/sessions \
155155

156156
---
157157

158+
## Session Export
159+
160+
Download the full session transcript as JSONL (NDJSON) or Markdown. Useful for archiving, sharing results, or feeding session context into other tools.
161+
162+
### Quick Example
163+
164+
```bash
165+
# Export as JSONL (default)
166+
curl "http://localhost:9100/v1/sessions/abc123/export" \
167+
-H "Authorization: Bearer $TOKEN" \
168+
-o session.jsonl
169+
170+
# Export as readable Markdown
171+
curl "http://localhost:9100/v1/sessions/abc123/export?format=markdown" \
172+
-H "Authorization: Bearer $TOKEN" \
173+
-o session.md
174+
```
175+
176+
### Formats
177+
178+
| Format | Query param | Content type | Best for |
179+
|--------|------------|-------------|----------|
180+
| JSONL | `?format=jsonl` (default) | `application/x-ndjson` | Programmatic processing, piping to jq, feeding into other tools |
181+
| Markdown | `?format=markdown` | `text/markdown` | Human review, sharing, pasting into docs |
182+
183+
### JSONL Output
184+
185+
Each line is a JSON object:
186+
187+
```json
188+
{"role":"user","contentType":"text","text":"Fix the auth bug","timestamp":"2026-05-10T15:00:00Z"}
189+
{"role":"assistant","contentType":"thinking","text":"Let me analyze the auth flow...","timestamp":"2026-05-10T15:00:01Z"}
190+
{"role":"assistant","contentType":"tool_use","text":"cat src/auth.ts","toolName":"Bash","timestamp":"2026-05-10T15:00:02Z"}
191+
{"role":"assistant","contentType":"text","text":"Found the issue — missing token expiry check.","timestamp":"2026-05-10T15:00:05Z"}
192+
```
193+
194+
Fields per entry:
195+
196+
| Field | Always present | Description |
197+
|-------|---------------|-------------|
198+
| `role` | ✅ | `user` or `assistant` |
199+
| `contentType` | ✅ | `text`, `thinking`, `tool_use`, `tool_result`, `tool_error` |
200+
| `text` | ✅ | Message content (truncated to 2000 chars in markdown) |
201+
| `toolName` | tool calls only | Name of the invoked tool (e.g. `Bash`, `Read`) |
202+
| `toolUseId` | tool calls only | Unique ID for the tool invocation |
203+
| `timestamp` | ✅ | ISO 8601 timestamp |
204+
205+
### Markdown Output
206+
207+
Renders a human-readable document:
208+
209+
```markdown
210+
# Session Export: fix-auth-bug
211+
212+
> Exported: 2026-05-10T15:30:00Z
213+
> Session ID: abc123
214+
> Status: idle
215+
216+
---
217+
218+
👤 **User:** Fix the auth bug
219+
220+
🤖 **Assistant:** Let me analyze the auth flow...
221+
222+
### 🔧 Tool: Bash
223+
<details>
224+
<summary>cat src/auth.ts</summary>
225+
226+
...file contents...
227+
</details>
228+
229+
🤖 **Assistant:** Found the issue — missing token expiry check.
230+
```
231+
232+
### Use Cases
233+
234+
**Archive completed sessions:**
235+
```bash
236+
# Export all completed sessions
237+
for sid in $(curl -s -H "Authorization: Bearer $TOKEN" \
238+
"http://localhost:9100/v1/sessions?status=idle&limit=100" | \
239+
jq -r '.sessions[].id'); do
240+
curl -s -H "Authorization: Bearer $TOKEN" \
241+
"http://localhost:9100/v1/sessions/$sid/export?format=jsonl" \
242+
-o "archives/$sid.jsonl"
243+
done
244+
```
245+
246+
**Share session results as a readable doc:**
247+
```bash
248+
curl -s -H "Authorization: Bearer $TOKEN" \
249+
"http://localhost:9100/v1/sessions/$SID/export?format=markdown" \
250+
-o result.md
251+
```
252+
253+
**Pipe JSONL into jq for analysis:**
254+
```bash
255+
# Count tool calls per tool name
256+
curl -s -H "Authorization: Bearer $TOKEN" \
257+
"http://localhost:9100/v1/sessions/$SID/export" | \
258+
jq -r '.toolName' | sort | uniq -c | sort -rn
259+
```
260+
261+
### Errors
262+
263+
| Status | Condition |
264+
|--------|----------|
265+
| `401` | Missing or invalid auth token |
266+
| `403` | Not the session owner |
267+
| `404` | Session not found or no transcript data available |
268+
| `400` | Invalid format (must be `jsonl` or `markdown`) |
269+
270+
---
271+
158272
## Session Templates
159273

160274
Session Templates let you save and reuse session configurations. Instead of repeating the same parameters for recurring tasks, create a template and reference it.

‎docs/competitive-threat-matrix.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Aegis Competitive Threat Matrix
2+
3+
> **Last updated:** 2026-05-10 | **Source:** Issues #3013, #3014, #3016, #3003, #3004 + ECC analysis (Orpheus)
4+
> **Audience:** Leadership (Ema, Boss) for strategic planning
5+
6+
---
7+
8+
## Executive Summary
9+
10+
The Claude Code orchestration space is **crowded and moving fast**. 8+ competitors with 200×–470× Aegis's star count. The market is bifurcating into **simple developer tools** (win on ease-of-use) and **enterprise platforms** (win on depth and governance). Aegis is an enterprise platform — the moat is real but the **simplicity gap is existential**.
11+
12+
**Bottom line:** We cannot out-feature ruflo (47K ⭐, 98 agents, 314 MCP tools). We cannot out-simplify oh-my-claudecode (33K ⭐, zero-config install). We *can* own the **enterprise orchestration middleware** niche — API-first, compliant, auditable — if we close the install friction gap and ship multi-agent support.
13+
14+
---
15+
16+
## Threat Matrix
17+
18+
| Rank | Competitor | ⭐ | Threat | Installs in | Agent count | Chat platforms | API | Dashboard | Enterprise auth |
19+
|------|-----------|-----|--------|-------------|-------------|---------------|-----|-----------|----------------|
20+
| #1 | **Ruflo** | 47K | 🔴 CRITICAL | `npx ruflo init` | 98 | UI only | ✅ (undocumented) | ✅ (beta) | ❌ |
21+
| #2 | **oh-my-claudecode** | 33K | 🔴 CRITICAL | `/plugin install` (1 cmd) | Multi-agent | Plugin (inside CC) | ❌ | ❌ | ❌ |
22+
| #3 | **cc-connect** | 8K | 🟠 HIGH | Binary download | 10+ | **11** (inc. WeChat, QQ) | ❌ | ✅ (basic) | Token only |
23+
| #4 | **Composio** | 6.9K | 🟠 HIGH | `npm install` | Multi-agent | CI/CD focus | ✅ | ❌ | ❌ |
24+
| #5 | **open-multi-agent** | 6.1K | 🟡 MEDIUM | `npm install` | Multi-agent | MCP only | ✅ | Tracing UI | ❌ |
25+
| #6 | **mission-control** | 4.7K | 🟠 HIGH | `npm install` | Multi-gateway | Skills Hub | ✅ | ✅ | ✅ RBAC |
26+
| #7 | **OpenACP** | 346 | 🟠 HIGH | `curl \| bash` | **28+** | Telegram, Discord, Slack | ✅ | ❌ | ❌ |
27+
| #8 | **ECC** | 177K | 🟢 OPPORTUNITY | Config library | N/A (skills) | N/A | ❌ | ❌ | ❌ |
28+
| — | **Aegis** | ~200 | — | `npm + init + config` | 1 (Claude Code) | 4 | ✅ 34 MCP tools | ✅ Full React | ✅ OIDC/RBAC |
29+
30+
---
31+
32+
## Aegis-Only Features (Our Moat)
33+
34+
No single competitor has ALL of these. This is the enterprise wedge:
35+
36+
- ✅ Full REST API (65+ endpoints) with CRUD + pagination
37+
- ✅ MCP server (34 tools)
38+
- ✅ SSE real-time event streaming
39+
- ✅ OIDC/SSO enterprise auth + RBAC roles
40+
- ✅ Audit trail with hash chain integrity
41+
- ✅ OpenTelemetry tracing
42+
- ✅ Billing/metering with cost tracking
43+
- ✅ TypeScript + Python client SDKs
44+
- ✅ Kubernetes / Helm deployment
45+
- ✅ Sigstore release signing
46+
- ✅ Session templates + pipeline orchestration
47+
- ✅ Memory Bridge (cross-session state)
48+
- ✅ Session export (JSONL download)
49+
50+
---
51+
52+
## Critical Gaps (What Competitors Have That We Don't)
53+
54+
| Gap | Impact | Who has it | Priority |
55+
|-----|--------|-----------|----------|
56+
| **Multi-agent support** | Existential — every competitor supports 2+ agents | All except ECC | P0 |
57+
| **Simple install** (≤2 commands) | Users never reach Aegis if OMC is easier | OMC, OpenACP, Ruflo | P0 |
58+
| **Plugin marketplace distribution** | 177K-star audience unreachable | OMC (CC marketplace) | P1 |
59+
| **Chat platform breadth** | Missing entire Asian market (WeChat, QQ, DingTalk) | cc-connect (11 platforms) | P1 |
60+
| **Natural language scheduling** | Dev productivity killer feature | cc-connect | P2 |
61+
| **Self-learning memory** | Agents improve over time | Ruflo | P2 |
62+
| **Multi-language docs** | International adoption blocked | OMC (6 languages), cc-connect (5) | P2 |
63+
64+
---
65+
66+
## Strategic Recommendations
67+
68+
### Immediate (v0.7.0)
69+
1. **Close the install gap** — `ag run "task"` is a start. Make it the default. Zero-config should be 1 command, not 4.
70+
2. **Multi-agent support** — at minimum, add Codex and Gemini as runner backends (ACP already supports them)
71+
3. **ACP registry listing** — register Aegis for discoverability
72+
73+
### Short-term (v0.8.0)
74+
4. **Claude Code plugin marketplace** — get Aegis listed as a plugin, not just an npm package
75+
5. **ECC integration guide** — "Run ECC Skills as a Service with Aegis" captures their 177K-star audience
76+
6. **Discord channel** — cc-connect has it, we don't
77+
78+
### Medium-term (v1.0)
79+
7. **Asian market** — WeChat, QQ, DingTalk adapters
80+
8. **Natural language scheduling** — "every Monday at 9am, run tests"
81+
9. **Multi-language docs** — at minimum EN + ZH + JA
82+
83+
### Defensive Positioning
84+
> **"ECC makes your agents smart. Aegis makes them accessible."** — Orpheus
85+
86+
This is the tagline. Ruflo and OMC are developer tools. Aegis is **enterprise middleware** — the layer between "someone typed a message" and "code shipped to production." The moat is compliance, governance, observability. Don't compete on agent count. Compete on trust.
87+
88+
---
89+
90+
## Competitor Detail References
91+
92+
| Issue | Competitor | Key takeaway |
93+
|-------|-----------|-------------|
94+
| #3013 | Ruflo (47K ⭐) | Full-stack, 98 agents, self-learning. Enterprise moat still defensible. |
95+
| #3014 | oh-my-claudecode (33K ⭐) | Zero-config is our biggest UX gap. `/autopilot` mode to replicate. |
96+
| #3004 | cc-connect (8K ⭐) | 11 chat platforms, multi-agent. Converging on our enterprise features. |
97+
| #3003 | OpenACP (346 ⭐) | Same architecture, simpler install, 28+ agents. Highest-threat small competitor. |
98+
| #3016 | Full landscape | 8 competitors ranked. Aegis smallest by stars, deepest by enterprise features. |
99+
| ECC | everything-claude-code (177K ⭐) | Not a competitor — distribution channel. Skills layer, not orchestration. |
100+
101+
---
102+
103+
*Maintained by Scribe 📝 — update on each competitive scan.*

‎docs/getting-started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -353,7 +353,7 @@ See [`packages/python-client/`](../packages/python-client/) for source and the f
353353
- **[MCP Tools Reference](./mcp-tools.md)** — Full documentation for all 34 MCP tools
354354
- **[API Reference](./api-reference.md)** — Complete REST API documentation
355355
- **[Verifying Releases](./verify-release.md)** — SHA verification, npm integrity, Sigstore attestations, version policy
356-
- **[Advanced Features](./advanced.md)** — Pipelines, Memory Bridge, templates
356+
- **[Advanced Features](./advanced.md)** — Session Export, Pipelines, Memory Bridge, templates
357357
- **[Enterprise Deployment](./enterprise.md)** — Auth, rate limiting, production setup
358358
- **[ACP Migration Guide](./acp-migration-guide.md)** — Upgrading from `aegis-bridge`
359359
- **[TypeDoc API](https://onestepat4time.github.io/aegis/)** — Auto-generated TypeScript reference

0 commit comments

Comments
 (0)