Skip to content

Commit a12d474

Browse files
OracleNepOracleNep
committed
docs: clarify purpose compatibility and setup
1 parent 4fb7a7b commit a12d474

1 file changed

Lines changed: 166 additions & 82 deletions

File tree

‎README.md‎

Lines changed: 166 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -2,52 +2,164 @@
22

33
English | [简体中文](README.zh-CN.md)
44

5-
AgentFlowDesk is a **local-first task board and context manager for AI coding agents**.
5+
AgentFlowDesk is a **local-first workflow manager for AI coding agents**.
66

7-
It helps developers turn AI-agent work into structured, reviewable, and reusable workflows:
7+
It is **not** a Claude Skill, MCP server, IDE extension, browser plugin, or another chatbot. It is a small Python CLI that sits **outside** your AI coding agent and helps you manage the work around it:
88

9-
- Plan coding tasks before sending them to an agent
10-
- Build compact **Context Packs** for each task
11-
- Export instructions to `AGENTS.md`, `CLAUDE.md`, Cursor rules, Codex instructions, and `GEMINI.md`
12-
- Run an optional local agent command and capture prompt, logs, diff, checks, and review report
13-
- Keep AI-agent work auditable instead of scattered across chat windows
9+
```text
10+
Task → Context Pack → Agent instructions → Agent command → Logs + Diff + Checks → Review Report
11+
```
1412

15-
> MVP status: CLI-first. The web task board is planned after the core workflow is stable.
13+
In plain terms: AgentFlowDesk prepares clean task context for tools like Claude Code, Codex CLI, Cursor, Gemini CLI, and OpenCode, then records what was sent, what ran, what changed, and what still needs human review.
14+
15+
> MVP status: v0.1.0, CLI-first. No server is required. The web task board is planned after the core workflow is stable.
1616
>
1717
> CI note: the test workflow validates installation and the core Context Pack/export/run path on Python 3.10, 3.11, and 3.12.
1818
19-
## Why this exists
19+
## What exactly is it?
2020

21-
AI coding agents are powerful, but day-to-day usage still has friction:
21+
AgentFlowDesk is a **local Python command-line tool** for developers who already use AI coding agents.
2222

23-
1. Context has to be copied and rewritten repeatedly.
24-
2. Agent output is hard to review after the session ends.
25-
3. Running multiple agents or tasks in parallel is messy.
26-
4. Successful prompts and workflows are not easy to reuse.
27-
5. Users need a lightweight way to connect task intent, context, diff, tests, and human review.
23+
It gives those agents a structured workflow layer:
24+
25+
- **Task manager**: define a small coding task with goal, files, notes, and acceptance criteria.
26+
- **Context Pack builder**: generate a reproducible prompt bundle for that task.
27+
- **Instruction exporter**: write `AGENTS.md`, `CLAUDE.md`, Cursor rules, Codex instructions, and `GEMINI.md` from the same task context.
28+
- **Command wrapper**: optionally run an installed local agent CLI with the generated prompt.
29+
- **Run recorder**: save prompt, stdout, stderr, git diff, check results, and review report under `.agentflow/`.
30+
31+
It does **not** provide a model by itself. It does **not** call Claude, Codex, OpenCode, or Gemini unless you explicitly configure a command for it.
32+
33+
## Compatibility
34+
35+
AgentFlowDesk is compatible in two ways:
36+
37+
1. **File-based context**: export a task into instruction files that coding agents already understand or that users can paste into them.
38+
2. **Command-wrapper mode**: run any local CLI command and replace `{prompt}` with the generated Context Pack path.
39+
40+
| Tool | Current support | How to use it |
41+
|---|---|---|
42+
| Claude Code | Yes | Export `CLAUDE.md`, or run a local command such as `claude < {prompt}` if your installed Claude Code CLI accepts stdin. |
43+
| Codex CLI | Yes | Export `AGENTS.md` and `.codex/instructions.md`, or wrap your installed Codex command with `{prompt}`. |
44+
| OpenCode | Yes, generic CLI mode | Export `AGENTS.md` / use the generated `context-pack.md`, or wrap your installed `opencode` command if it accepts a prompt file or stdin. Dedicated preset is planned. |
45+
| Cursor | Yes, file export | Export `.cursor/rules/agentflow.mdc`; then use Cursor normally in the project. |
46+
| Gemini CLI | Yes | Export `GEMINI.md`, or wrap your local Gemini CLI command. |
47+
| Any other coding agent CLI | Usually yes | Works if the tool can read a prompt file, read stdin, or use a project instruction file. |
48+
49+
Compatibility here means **workflow-level integration**, not an official plugin contract. Agent-specific command flags change over time, so AgentFlowDesk keeps the core generic: you decide the command, AgentFlowDesk provides `{prompt}` and records the run.
50+
51+
## Installation
52+
53+
### Requirements
54+
55+
- Python 3.10+
56+
- Git, recommended for diff capture
57+
- Optional: Claude Code, Codex CLI, OpenCode, Gemini CLI, or another local coding-agent CLI
58+
59+
### Install from source
60+
61+
```bash
62+
git clone https://github.com/OracleNep/AgentFlowDesk.git
63+
cd AgentFlowDesk
64+
python -m venv .venv
65+
source .venv/bin/activate # Windows: .venv\Scripts\activate
66+
python -m pip install -U pip
67+
python -m pip install -e .[dev]
68+
```
69+
70+
Verify installation:
71+
72+
```bash
73+
agentflow --help
74+
pytest -q
75+
```
2876

29-
AgentFlowDesk does not try to replace Claude Code, Codex CLI, Cursor, Gemini CLI, or OpenCode. It gives them a structured workflow layer.
77+
## Deploy / start in a real project
3078

31-
## Quick start
79+
AgentFlowDesk has no daemon and no web service in the MVP. To "deploy" it, install the CLI and initialize it inside the codebase where you want to use agents.
3280

3381
```bash
34-
python -m pip install -e .
35-
agentflow init --name MyProject --description "Demo project using AI coding agents"
82+
cd /path/to/your/project
83+
agentflow init --name MyProject --description "Project managed with AI coding agents"
84+
```
85+
86+
This creates local metadata under:
87+
88+
```text
89+
.agentflow/
90+
config.json
91+
tasks.json
92+
runs.json
93+
context/
94+
runs/
95+
```
96+
97+
By default, AgentFlowDesk stores data locally and does not upload your code or prompt anywhere.
3698

99+
## Basic workflow
100+
101+
### 1. Create a task
102+
103+
```bash
37104
agentflow task create \
38105
--title "Add SARIF ruleId support" \
39106
--goal "Modify the SARIF reporter so each finding has a stable ruleId." \
40107
--file src/reporters/sarif.py \
41108
--acceptance "Unit tests pass" \
42109
--acceptance "No unrelated files changed" \
43110
--agent claude-code
111+
```
44112

113+
List and inspect tasks:
114+
115+
```bash
45116
agentflow task list
117+
agentflow task show AF-20260613-001
118+
```
119+
120+
### 2. Build a Context Pack
121+
122+
```bash
46123
agentflow context build AF-20260613-001
47-
agentflow export AF-20260613-001 --target agents --target claude --force
48124
```
49125

50-
Run an agent command or any local command:
126+
Generated files:
127+
128+
```text
129+
.agentflow/context/<task-id>/
130+
task-brief.md
131+
agent-instructions.md
132+
commands.md
133+
environment.md
134+
relevant-files.md
135+
context-pack.md
136+
```
137+
138+
### 3. Export instructions for your agent
139+
140+
```bash
141+
agentflow export AF-20260613-001 \
142+
--target agents \
143+
--target claude \
144+
--target cursor \
145+
--target codex \
146+
--target gemini \
147+
--force
148+
```
149+
150+
Export targets:
151+
152+
| Target | Output file |
153+
|---|---|
154+
| `agents` | `AGENTS.md` |
155+
| `claude` | `CLAUDE.md` |
156+
| `cursor` | `.cursor/rules/agentflow.mdc` |
157+
| `codex` | `.codex/instructions.md` |
158+
| `gemini` | `GEMINI.md` |
159+
160+
### 4. Run a command and record the result
161+
162+
Use a safe manual smoke test first:
51163

52164
```bash
53165
agentflow run AF-20260613-001 \
@@ -56,7 +168,25 @@ agentflow run AF-20260613-001 \
56168
--check "pytest -q"
57169
```
58170

59-
`{prompt}` is replaced with the generated context-pack path.
171+
Example with Claude Code, if your CLI accepts stdin:
172+
173+
```bash
174+
agentflow run AF-20260613-001 \
175+
--agent claude-code \
176+
--command "claude < {prompt}" \
177+
--check "pytest -q"
178+
```
179+
180+
Example with a custom command:
181+
182+
```bash
183+
agentflow run AF-20260613-001 \
184+
--agent opencode \
185+
--command "opencode < {prompt}" \
186+
--check "pytest -q"
187+
```
188+
189+
If your agent CLI uses a different flag for prompt files, just replace the command. `{prompt}` is always substituted with the generated `context-pack.md` path.
60190

61191
After a run, AgentFlowDesk creates:
62192

@@ -69,55 +199,19 @@ After a run, AgentFlowDesk creates:
69199
review-report.md
70200
```
71201

72-
## Core concepts
73-
74-
### Task
75-
76-
A task is a small unit of agent work:
77-
78-
```yaml
79-
title: Add SARIF ruleId support
80-
goal: Modify the SARIF reporter so each finding has a stable ruleId.
81-
files:
82-
- src/reporters/sarif.py
83-
acceptance:
84-
- Unit tests pass
85-
- No unrelated files changed
86-
```
87-
88-
### Context Pack
89-
90-
A context pack is a generated prompt bundle containing:
91-
92-
- task brief
93-
- agent instructions
94-
- project commands
95-
- file tree and git status
96-
- relevant file excerpts
97-
98-
### Export Target
99-
100-
AgentFlowDesk can export the same task context to multiple agent instruction formats:
101-
102-
| Target | Output file |
103-
|---|---|
104-
| `agents` | `AGENTS.md` |
105-
| `claude` | `CLAUDE.md` |
106-
| `cursor` | `.cursor/rules/agentflow.mdc` |
107-
| `codex` | `.codex/instructions.md` |
108-
| `gemini` | `GEMINI.md` |
202+
## Why this exists
109203

110-
### Run
204+
AI coding agents are powerful, but day-to-day usage still has friction:
111205

112-
A run captures one attempt to complete a task. It stores:
206+
1. Context has to be copied and rewritten repeatedly.
207+
2. Agent output is hard to review after the session ends.
208+
3. Running multiple agents or tasks in parallel is messy.
209+
4. Successful prompts and workflows are not easy to reuse.
210+
5. Users need a lightweight way to connect task intent, context, diff, tests, and human review.
113211

114-
- generated prompt
115-
- stdout / stderr
116-
- git diff
117-
- check command results
118-
- review report
212+
AgentFlowDesk turns disposable agent sessions into reviewable engineering artifacts.
119213

120-
## Example workflow
214+
## Example review flow
121215

122216
```bash
123217
agentflow init
@@ -130,11 +224,7 @@ agentflow task create \
130224
--acceptance "public CLI behavior remains unchanged"
131225

132226
agentflow export AF-20260613-001 --target claude --force
133-
134-
# Use your preferred agent manually, or wrap a CLI command:
135227
agentflow run AF-20260613-001 --command "claude < {prompt}" --check "pytest -q"
136-
137-
# Review generated report:
138228
cat .agentflow/runs/*/review-report.md
139229
```
140230

@@ -145,26 +235,20 @@ cat .agentflow/runs/*/review-report.md
145235
- [x] Context Pack generation
146236
- [x] Export to common agent instruction files
147237
- [x] Run record with prompt, logs, diff, checks, and review report
238+
- [x] GitHub Actions CI
239+
- [x] Basic test coverage for the core workflow
148240
- [ ] Git worktree isolation for parallel agent runs
149241
- [ ] YAML sprint batch runner
150242
- [ ] Web UI task board
151243
- [ ] Reusable skill/prompt library
152244
- [ ] Cost and token estimation
153245
- [ ] Agent adapter presets for Claude Code, Codex CLI, Gemini CLI, OpenCode, and Cursor workflows
154246

155-
## Design goal
156-
157-
AgentFlowDesk is intentionally boring infrastructure. It is not another chatbot.
158-
159-
The goal is to make AI-agent development work:
160-
161-
```text
162-
Task → Context Pack → Agent Run → Diff + Checks → Human Review → Reusable Workflow
163-
```
164-
165247
## Safety and privacy
166248

167-
AgentFlowDesk is local-first. It stores files under `.agentflow/` inside your project. It does not send code to a remote service by itself. If you use it to call an external agent CLI, that CLI's own behavior and privacy policy apply.
249+
AgentFlowDesk is local-first. It stores files under `.agentflow/` inside your project. It does not send code to a remote service by itself.
250+
251+
If you use it to call an external agent CLI, that CLI's own behavior and privacy policy apply.
168252

169253
## License
170254

0 commit comments

Comments
 (0)