Skip to content

Commit 9779aa3

Browse files
OneStepAt4timeOneStepAt4time
authored
docs(README): correct ag setup telegram to ag init + phone-approvals guide (#4614)
Expands the hotfix branch with two doc backports to close the link-integrity gap, plus a test fix for date-dependent flakiness in getDailyTokenBreakdown tests.
1 parent ab92415 commit 9779aa3

4 files changed

Lines changed: 432 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ ag run "Your prompt here" --cwd ./my-project
7878
After your first session, you might want to:
7979

8080
- **Dashboard** — open <http://127.0.0.1:9100/dashboard> to see sessions, cost analytics, and audit trails
81-
- **Telegram** — approve agent actions from your phone: `ag setup telegram` (one guided setup)
81+
- **Telegram** — approve agent actions from your phone: run `ag init` and follow the Telegram setup prompt, or see the [Phone Approvals guide](docs/guides/phone-approvals.md)
8282
- **MCP** — let Claude Code control Aegis: `claude mcp add --scope user aegis -- ag mcp`
8383
- **Multiple sessions** — `ag run "fix the tests" & ag run "update the README"` (parallel agents)
8484

‎docs/five-minute-setup.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# 5-Minute Setup Guide
2+
3+
**From zero to your first Claude Code session — no config, no tokens, no friction.**
4+
5+
## What you need (1 minute)
6+
7+
- [Node.js ≥ 20](https://nodejs.org/) — check with `node --version`
8+
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) — check with `claude --version`
9+
- Claude Code authenticated — check with `claude auth status`
10+
11+
> Don't have Claude Code? Install it: `npm install -g @anthropic-ai/claude-code` then run `claude` to authenticate. This is the only thing that takes real time — do it first.
12+
13+
## Run your first session (2 minutes)
14+
15+
```bash
16+
npx --package=@onestepat4time/aegis ag run "Summarize this folder" --cwd ./my-project
17+
```
18+
19+
That's it. You'll see Claude's response stream directly in your terminal.
20+
21+
Behind the scenes, `ag run`:
22+
1. Bootstraps config (first run only — no prompts on localhost)
23+
2. Starts the server on `http://127.0.0.1:9100`
24+
3. Creates a Claude Code session
25+
4. Streams the response to your terminal
26+
27+
When Claude needs permission (to run a command, write a file), you'll see a prompt. Approve or deny right there.
28+
29+
> **Tip:** Run from a directory under your home folder (`~/projects/`, `~/code/`, etc.). System temp dirs (`/tmp`) are not allowed by default. If you need to allow additional directories, set `allowedWorkDirs` in `~/.aegis/config.yaml` — changes take effect immediately without restart.
30+
31+
<details>
32+
<summary>What you'll see</summary>
33+
34+
```
35+
🚀 ag run: Summarize this folder
36+
✅ Session: my-project (abc12345)
37+
📊 Dashboard: http://127.0.0.1:9100
38+
39+
📡 Streaming session output (Ctrl+C to stop)...
40+
41+
👤 Summarize this folder
42+
🤖 This project contains a Node.js web server with...
43+
```
44+
45+
</details>
46+
47+
## See it on the dashboard (30 seconds)
48+
49+
Open **http://127.0.0.1:9100/dashboard/** in your browser.
50+
51+
You'll see your session running, with status, cost tracking, and the full transcript.
52+
53+
## Manage sessions from the terminal (30 seconds)
54+
55+
```bash
56+
# List all sessions
57+
ag list
58+
59+
# Read a session's output (prefix matching works with ag read)
60+
ag read abc12345
61+
62+
# Stream output live
63+
ag tail abc12345-de12-4567-8910-abcdefgh1234
64+
65+
# Kill a session
66+
ag kill abc12345-de12-4567-8910-abcdefgh1234
67+
```
68+
69+
> Use `ag list --full-ids` to see complete UUIDs. `ag read` accepts short prefixes; `ag tail` and `ag kill` require the full UUID.
70+
71+
## Optional: Install globally (saves typing)
72+
73+
If you'll use Aegis regularly, install it globally — then you can skip the `npx` prefix:
74+
75+
```bash
76+
npm install -g @onestepat4time/aegis
77+
ag run "Your prompt here" --cwd ./my-project
78+
```
79+
80+
## Optional: Approve from your phone (1 minute)
81+
82+
Set two environment variables, then restart Aegis:
83+
84+
```bash
85+
export AEGIS_TG_BOT_TOKEN="<your-bot-token>"
86+
export AEGIS_TG_GROUP="<your-chat-id>" # positive for DM, negative for group
87+
```
88+
89+
Or add them to `aegis.config.json`:
90+
91+
```json
92+
{ "tgBotToken": "<token>", "tgGroupId": "<chat-id>" }
93+
```
94+
95+
After restart, Claude's permission prompts arrive on Telegram — approve or deny from anywhere.
96+
97+
> 📖 For the full walkthrough (create a bot, get chat ID, configure security), see the [Phone Approvals guide](./guides/phone-approvals.md).
98+
99+
## Optional: Let Claude Code control Aegis (30 seconds)
100+
101+
Register Aegis as an MCP server in Claude Code:
102+
103+
```bash
104+
claude mcp add --scope user aegis -- ag mcp
105+
```
106+
107+
Now Claude can create sessions, read transcripts, and manage Aegis directly through MCP tools.
108+
109+
## Flags you might use
110+
111+
| Flag | What it does |
112+
|------|-------------|
113+
| `--cwd <path>` | Project directory (default: current dir) |
114+
| `--name <name>` | Custom session name |
115+
| `--yes` | Suppress status messages (CI / non-interactive) |
116+
| `-y` | Auto-approve all permission prompts |
117+
| `--model <model>` | Override the model for this session |
118+
| `--effort <level>` | Reasoning effort: `low`, `medium`, `high` |
119+
| `--no-stream` | Wait for session completion and print output (non-streaming) |
120+
121+
## Troubleshooting
122+
123+
| Problem | Fix |
124+
|---------|-----|
125+
| `claude: command not found` | `npm install -g @anthropic-ai/claude-code` then `claude login` |
126+
| Session hangs without output | Run `claude auth status` — you must be logged in |
127+
| `workDir is not in the allowed directories list` | Run from your home directory, or add the path to `allowedWorkDirs` in `~/.aegis/config.yaml` |
128+
| `401 Unauthorized` | On localhost with a fresh install, this shouldn't happen. If it does, delete `~/.aegis/` and retry |
129+
| `EADDRINUSE` | Port 9100 in use: `AEGIS_PORT=9200 ag run "..." --cwd ./my-project` |
130+
| Dashboard won't load | Check Aegis is running: `curl http://127.0.0.1:9100/v1/health` |
131+
| Session stuck | Interrupt it: `ag kill <full-session-id>` |
132+
133+
## Next
134+
135+
- [Getting Started](./getting-started.md) — full configuration reference
136+
- [API Reference](./api-reference.md) — every endpoint documented
137+
- [MCP Tools](./mcp-tools.md) — 34 tools for multi-agent workflows
138+
- [Advanced Features](./advanced.md) — session export, pipelines, memory bridge
139+
140+
---
141+
142+
**Total time: ~5 minutes.** If it took longer, [file an issue](https://github.com/OneStepAt4time/aegis/issues/new) — that's a bug.

0 commit comments

Comments
 (0)