athena-graphs

Name: athena-graphs
Author: luckeyfaraday

byluckeyfaraday· 3 MCP servers

Stars

Forks

How to install athena-graphs?

luckeyfaraday/athena-graphs

$git clone https://github.com/luckeyfaraday/athena-graphs

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Install & use

Install athena-graphs by running `git clone https://github.com/luckeyfaraday/athena-graphs`, then use it for the current task and follow its documentation at https://github.com/luckeyfaraday/athena-graphs.

Files · 1

View on GitHub

README.md

1	# Athena Graphs
2
3	[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
4	[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-compatible-5B8CFF.svg)](plugins/athena-graphs/skills/athena-graphs/SKILL.md)
5
6	Give an agent a goal. Athena Graphs turns it into an explicit, durable graph of
7	specialized agent nodes—branches, joins, review loops, fallbacks, and human
8	checkpoints included.
9
10	No graph DSL or CLI flags in the normal workflow. Install the plugin and talk to
11	your agent:
12
13	> **Use Athena Graphs to implement authentication. Research the existing design
14	> and threat model in parallel, review the result, and pause before final
15	> approval.**
16
17	> ![Peter Steinberger: "Are we still talking loops or did we shift to graphs yet?"](docs/petergraphs.png)
18	>
19	> [Peter Steinberger (@steipete)](https://x.com/steipete):
20	> “Are we still talking loops or did we shift to graphs* yet?”*
21
22	## Install
23
24	Athena Graphs bundles one portable `SKILL.md` and one local MCP server. The same
25	runtime can drive Codex, Claude Code, OpenCode, Aider, Grok Build, model APIs, or
26	any Agent Skills–compatible host that can connect to MCP.
27
28	Prerequisites: Python 3.10+ and [`uv`](https://docs.astral.sh/uv/). No Python
29	package installation is required; the plugin launcher creates its environment
30	automatically on first use.
31
32	### Codex
33
34	```bash
35	codex plugin marketplace add luckeyfaraday/athena-graphs
36	codex plugin add athena-graphs@athena-graphs
37	```
38
39	Start a new Codex thread and say:
40
41	```text
42	Use Athena Graphs to build this feature and keep me updated.
43	```
44
45	You can also invoke the skill explicitly with `$athena-graphs`.
46
47	### Claude Code
48
49	```bash
50	claude plugin marketplace add luckeyfaraday/athena-graphs
51	claude plugin install athena-graphs@athena-graphs
52	```
53
54	Start a new session and ask naturally, or invoke:
55
56	```text
57	/athena-graphs:athena-graphs Build the feature and pause before final approval.
58	```
59
60	### Other skill-compatible agents
61
62	Install or link this skill directory using your agent's normal Agent Skills
63	mechanism:
64
65	```text
66	plugins/athena-graphs/skills/athena-graphs/
67	```
68
69	Then register the MCP server from
70	[`plugins/athena-graphs/.mcp.json`](plugins/athena-graphs/.mcp.json). If the host
71	does not provide `PLUGIN_ROOT` or `CLAUDE_PLUGIN_ROOT`, use an absolute plugin
72	path in an equivalent configuration:
73
74	```json
75	{
76	"mcpServers": {
77	"athena-graphs": {
78	"command": "uv",
79	"args": [
80	"run",
81	"--directory",
82	"/absolute/path/to/athena-graphs/plugins/athena-graphs",
83	"--extra",
84	"mcp",
85	"agentgraph-mcp"
86	]
87	}
88	}
89	}
90	```
91
92	## What using it feels like
93
94	The bundled skill handles the mechanics:
95
96	1. Inspect the target workspace and infer success criteria.
97	2. Design the smallest useful graph, or select the default.
98	3. Start it in the background through MCP.
99	4. Stream meaningful node progress while continuing the conversation.
100	5. Ask the user only when a human checkpoint is reached.
101	6. Resume from the durable checkpoint.
102	7. Inspect and verify the actual deliverable before reporting success.
103
104	The user never has to construct `--goal`, `--criteria`, backend, polling, or
105	resume commands.
106
107	```text
108	┌─▶ research ──┐
109	START ─▶ understand ─────┤ ├─▶ review ─┬─▶ END
110	└─▶ build ──────┘ │
111	▲ │ changes
112	└──── revise ◀─┘
113	```
114
115	Loops remain useful; a graph simply makes them one possible route alongside
116	branching, merging, parallel work, fallback paths, and human review.
117
118	![AI Agents: Loops vs Graphs](docs/loops-vs-graphs.png)
119
120	## Durable MCP tools
121
122	The plugin exposes:
123
124	- `graph_start` — validate and start a detached declarative graph.
125	- `graph_status` — inspect its current node, step, and running state.
126	- `graph_tail` — stream events and node output previews with a cursor.
127	- `graph_resume` — merge human answers into a checkpoint and continue.
128	- `graph_result` — retrieve final state, traces, errors, and diagram.
129	- `graph_diagram` — render proposed or running graphs as Mermaid.
130	- `graph_validate` — catch invalid nodes, routes, and joins before starting.
131	- `graph_list`, `list_backends`, and `doctor` — discovery and diagnostics.
132
133	Runs are stored under `~/.athena-graphs/runs` by default, or under
134	`ATHENA_GRAPHS_HOME` when configured. An MCP request never needs to stay open for
135	the duration of a coding agent.
136
137	## Declarative topology
138
139	The skill normally writes this for the user, but the MCP accepts plain JSON:
140
141	```json
142	{
143	"name": "research-build-review",
144	"max_steps": 12,
145	"nodes": [
146	{
147	"id": "research",
148	"kind": "agent",
149	"system": "Investigate without editing files.",
150	"prompt": "GOAL:\n$goal",
151	"output_key": "research"
152	},
153	{
154	"id": "build",
155	"kind": "agent",
156	"system": "Implement and verify the goal.",
157	"prompt": "GOAL:\n$goal\n\nRESEARCH:\n$research",
158	"output_key": "work_outpu

6 picks

Type

Install athena-graphs by running `git clone https://github.com/luckeyfaraday/athena-graphs`, then use it for the current task and follow its documentation at https://github.com/luckeyfaraday/athena-graphs.

athena-graphs

How to install athena-graphs?

Related

athena-graphs

How to install athena-graphs?

Related