English | 日本語
gy aims to free you from the chores of "telling the AI the context it needs, and organizing that context so it gets across", so that you finish your work sooner and go home earlier. Concretely, it takes the large amount of context that arises "after the need, before the deliverable" and holds it, together with strict invariants, as a graph of the following nodes and edges.
flowchart LR
N[Need]
Q[Question]
D[Decision]
R[Requirement]
AC[Acceptance criterion]
N -- spawned-by --> D
N -- filed-as --> R
N -- waits-on --> Q
N -- waits-on --> R
N -- depends-on --> N
N -- targets --> AC
R -- targets --> AC
R -- relies-on --> D
R -- raised --> Q
Q -- closes --> D
D -- "narrows /<br> widens /<br> supersedes /<br> completes" --> D
Using it is simple:
- Make the AI aware of gy
(a skill named
gy-loopis bundled, so telling it "from today, let's work along gy-loop" is enough) - Tell it what you want to do and why it is needed
That is all. From then on, even in a new session, ask the AI "what's next?" and it tells you what to do next. Details come later, but the moment gy helps most is when you overturn one of your own past decisions.
cargo install gy
# optional (the quick way to tell the AI about `gy`)
npx skills add aq2bq/gyOnce a day gy runs cargo info gy to check for a newer release, and gy handover and gy next tell you when there is one. Unless you share a ledger with a team, that is the only network request gy makes.
Install with cargo install gy --version 3.0.0 --locked. For a shared ledger,
update every member before anyone uses gy retire: the first retirement raises
the ledger to format 5, which gy 2.x cannot read. Restoring the nodes keeps
format 5. Ordinary writes without retirement keep format 4; no manual log
migration or gy.toml change is needed.
The skills changed, so copy them again: update
crates/gy/skills/gy-ledger/SKILL.md in the installed skill directory (for
example ~/.agents/skills/gy-ledger/SKILL.md), or rerun
npx skills add aq2bq/gy. Repeating installation or copying the skill is safe.
See 3.0.0 in the changelog.
Put a sentence like the following in a prompt or in AGENTS.md / CLAUDE.md so it gets across, and the AI agent resumes from gy handover and gy next every time.
This project tracks its progress in gy. Before you start or resume anything, read the gy-loop skill and follow the record.
The record itself is saved by default under $XDG_DATA_HOME/gy/<hash of the repository root>/. Unless you set up team sharing (described below), gy never goes out to the network. Putting it inside the project's repository is not recommended, because the cycle of changes "after the need, before the deliverable" and the cycle of changes to the deliverable are completely different.
Still experimental, but
gy remote set https://github.com/you/yourproject-gy.gitsets a remote repository, and from then on gy remote sync is called in the background to keep it in sync. To share gy with other members, share the repository and have them run gy remote join. That is all.
- I built this feature over a holiday week, so the author has not used it with a team
- More than whether the sync mechanism works, I expect it will not go well without some discipline that gy cannot cover
- The explanation at every resume goes away. After resetting a session you no longer write "we are at this issue, the process is in this file, last time we finished this PR, next is X". The agent starts from
gy handoverandgy next. - On "how much, and what, to tell the AI" when conveying a need: telling it in detail leads to the questions and the acceptance criteria being on the table early, and telling it "a rough fantasy for now" leads to a way of working where the necessary decisions are postponed. In the end, the number of decisions needed does not change.
- When you overturn a past decision, the new decision cannot be written without quoting which part of the old decision loses effect. The mark goes on the quoted passage only, and the rest stays in force. gy does not find the contradiction for you. Because the work being picked up is connected to that decision node by edges, the AI can understand which decisions are in force.
What remains for the human is deciding, and only deciding. Goals and needs, and answers to the questions and options the AI presents. The first line of gy-loop says the same: "A person cannot escape the critical decisions. gy frees them from everything else."
To look at the record yourself, use gy serve. The screenshots show a demo ledger built by scripts/demo-ledger.sh. Before you have a record of your own, run it and gy serve to see the same.
gy serve opens on progress: the open needs by scope and how far they got, what holds them and which root holds the most, the weeks, and what nobody holds.
The home is the person's view of today: the three counts under the wordmark — who waits, what is ready, and what is half-done — then the newest writes. Each box opens the rows it counts, and a list of any kind sits under the entrances.
A word, a period, or a scope narrows the record. The set is drawn with rows for scopes and time across, with its scale and what happened in the period. With no narrowing, the screen gives the scope × week grid instead of every node.
The detail screen puts where a node came from on the left and what it works on on the right; pressing a box centers it. The facts, the body, and the writes stay below.
The sidebar is the way around: progress (the first screen), home, across, the lists of each kind, the scopes, the search (⌘K or /), and the history. The wordmark goes back to progress. On a wide screen the rail shows the ten newest writes as they land.
| Node | What it is |
|---|---|
need n-… |
What you want done. Points at acceptance criteria |
question q-… |
Something to decide, with a decider and at least two options |
decision d-… |
What was decided, what it is for, and where it holds |
requirement r-… |
A promise of what will be built. Work starts after it is approved |
criterion ac-… |
What has to be true for the work to count as finished |
A criterion can be recorded as satisfied only while an approved requirement points at it. Who approves is up to you, not gy.
A criterion that only needs closed with need close aimed at is read as withdrawn: the close's evidence is its reason, it is no longer counted as unmet, and gy show names it.
Every write needs a name in GY_ACTOR. If the tool that starts you already sets one, keep it; otherwise give each agent its own name. The history then shows who wrote what and why.
gy cheat lists them, but every write prints the commands you can type next, so there is nothing to memorize. gy undo takes back the last write, and the undo stays in the history too. gy publish writes the ledger out as a Markdown wiki you can read on GitHub.
An agent can select records that should no longer be read, such as records of
how the work was run, and use gy retire <ID>... --reason <text>. gy does not
choose candidates or judge their meaning. It refuses in-progress nodes and any
edge between retired and visible nodes; select a connected set in one write.
Retired nodes disappear from the readings, including past sequences in
gy serve. A direct gy show <ID> gives the retirement sequence and how to
restore the node. list --since, list --actor, and the web history keep the
retirement write's IDs and reason. Textual references in surviving records
remain unchanged. Original text remains in the log, snapshots, and remote git.
The next gy publish rewrites the scope's directory without the retired pages.
Restore the set with gy retire <ID>... --revoke --reason <text>, or use
gy undo immediately after retiring it. Restoring only part of a connected set
is refused. Repeating a retirement or restoration already in effect is refused
without writing another transaction; running undo again redoes its last undo.
gy init <scope> creates it. It holds only the scope names, plus the publish output directory and the remote if you want them.
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --lockedThe workspace holds gy-ledger (the store, model, and operations), gy-serve (the read-only web view), and gy (the CLI). CI tests on Linux; other platforms are unverified. The screens of gy serve have their own end-to-end tests under e2e/ (Playwright, chromium): see e2e/README.md; they are not part of cargo test.