attraverso 0.1.3 → 0.2.0
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 +98 -0
- package/assets/migrations/0014_past_chronomancer.sql +3 -0
- package/assets/migrations/meta/0014_snapshot.json +1609 -0
- package/assets/migrations/meta/_journal.json +7 -0
- package/migrations/0014_past_chronomancer.sql +3 -0
- package/migrations/meta/0014_snapshot.json +1609 -0
- package/migrations/meta/_journal.json +7 -0
- package/package.json +2 -2
- package/server.js +81 -22
- package/viewer/assets/{index-BW6lgiAa.css → index--Q2Bqrsm.css} +1 -1
- package/viewer/assets/index-Dk0TlY7z.js +90 -0
- package/viewer/index.html +2 -2
- package/README.txt +0 -10
- package/viewer/assets/index-CBMcK_jK.js +0 -90
package/README.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# attraverso
|
|
2
|
+
|
|
3
|
+
Durable, structured project memory for AI coding agents, over [MCP](https://modelcontextprotocol.io).
|
|
4
|
+
|
|
5
|
+
An agent is good at working on a project and bad at remembering it three weeks later. The usual workaround is
|
|
6
|
+
a `CLAUDE.md` file that grows unmaintainably, cannot be queried, and rots. Attraverso moves that state into a
|
|
7
|
+
real store: the plan, the reasoning behind it, and the record of what was decided - retrieved as a
|
|
8
|
+
budget-bounded slice rather than dumped into context wholesale.
|
|
9
|
+
|
|
10
|
+
The plan lives as version-controlled YAML committed alongside your code, so it is reviewable in a pull request
|
|
11
|
+
like any other file, and is rebuilt into an in-memory Postgres ([PGlite](https://pglite.dev)) on load.
|
|
12
|
+
|
|
13
|
+
## Using it
|
|
14
|
+
|
|
15
|
+
Requires Node 22 or newer.
|
|
16
|
+
|
|
17
|
+
### In Claude Code
|
|
18
|
+
|
|
19
|
+
Add it to the `.mcp.json` at the root of your repo:
|
|
20
|
+
|
|
21
|
+
```json
|
|
22
|
+
{
|
|
23
|
+
"mcpServers": {
|
|
24
|
+
"attraverso": {
|
|
25
|
+
"command": "npx",
|
|
26
|
+
"args": ["-y", "attraverso"]
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The plan, `attraverso.yaml`, is created at the root of the repo on first run. Commit it: it is the source of
|
|
33
|
+
truth, and its diffs are the history of the plan. Readings and attachments go in an `.attraverso/` folder
|
|
34
|
+
beside it, committed too.
|
|
35
|
+
|
|
36
|
+
Then ask the agent to call `get_project`, or just to create a project and start planning. The tools describe
|
|
37
|
+
themselves, and `get_project` returns the project's protocol - its operating manual - first.
|
|
38
|
+
|
|
39
|
+
### Where the plan lives
|
|
40
|
+
|
|
41
|
+
In order of precedence:
|
|
42
|
+
|
|
43
|
+
1. `--store <path>` (repeatable: a plan can span several files), or `APM_STORE_PATH`.
|
|
44
|
+
2. The nearest `attraverso.yaml` found walking up from the working directory, like `tsconfig.json`. Inside a git
|
|
45
|
+
repo the search stops at the repo's root.
|
|
46
|
+
3. In a git repo with no plan yet, `attraverso.yaml` at the repo's root, created on first run.
|
|
47
|
+
4. Outside any repo, `~/.ai-project-manager/attraverso.yaml`, for a personal project with no repo to live in.
|
|
48
|
+
|
|
49
|
+
To keep the plan somewhere else - under another name, in a subfolder, or one file shared by several repos -
|
|
50
|
+
name it with `--store`. A relative path is resolved from the repo root, where Claude Code starts the server:
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
"args": ["-y", "attraverso", "--store", "../plans/shared.yaml"]
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Repeat `--store` to load a plan split across files; the first one named is where new projects go.
|
|
57
|
+
|
|
58
|
+
**Plan files from before 0.1.2 are named `*.apm.yaml`**, with their data in `.apm/`. They are still found and
|
|
59
|
+
loaded, and always will be. To move one over, rename both: `git mv roadmap.apm.yaml attraverso.yaml` and
|
|
60
|
+
`git mv .apm .attraverso`.
|
|
61
|
+
|
|
62
|
+
### Seeing it
|
|
63
|
+
|
|
64
|
+
Ask the agent to open the viewer (the `open_viewer` tool). It serves the plan as a dependency graph on a
|
|
65
|
+
`127.0.0.1` address, so it only opens on the machine running the server.
|
|
66
|
+
|
|
67
|
+
### Claude Desktop
|
|
68
|
+
|
|
69
|
+
Claude Desktop starts servers without your shell's `PATH`, so a bare `npx` or `node` is often not found. See
|
|
70
|
+
[docs/claude-desktop.md](docs/claude-desktop.md) for the setup and the three ways it silently breaks.
|
|
71
|
+
|
|
72
|
+
## Developing
|
|
73
|
+
|
|
74
|
+
```sh
|
|
75
|
+
yarn install
|
|
76
|
+
yarn verify # typecheck, viewer build, unit tests
|
|
77
|
+
yarn verify:all # plus the end-to-end suite (once: npx playwright install chromium)
|
|
78
|
+
yarn viewer # the graph on http://localhost:5176
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
`yarn test:pg` runs the same suite against a server Postgres (`yarn pg:up` starts one in Docker).
|
|
82
|
+
|
|
83
|
+
To try a change against a real plan, run the server from source over any store: `yarn mcp:dev --store
|
|
84
|
+
<path>`, or point a `.mcp.json` at `node_modules/.bin/vite-node src/mcp/server.ts`.
|
|
85
|
+
|
|
86
|
+
Releasing is `yarn release` (`--dry-run` to rehearse), from an up-to-date checkout of this repo: it verifies,
|
|
87
|
+
builds, checks the build starts with clean stdout, publishes to npm and tags the version. The published package
|
|
88
|
+
is a single self-contained build that needs nothing installed but Node.
|
|
89
|
+
|
|
90
|
+
## How this repo is maintained
|
|
91
|
+
|
|
92
|
+
Attraverso is developed in a private repository alongside a hosted version, and the open core is mirrored here
|
|
93
|
+
automatically. Issues and pull requests are welcome here; a merged pull request is carried across to the
|
|
94
|
+
private repository with its authorship kept, and comes back out in the next export.
|
|
95
|
+
|
|
96
|
+
## Licence
|
|
97
|
+
|
|
98
|
+
[Apache-2.0](LICENSE).
|