Forem: Ahmed Fayyaz

Spine v1: Stop Making Claude Rediscover Your Codebase Every Time You Open a Repo

Ahmed Fayyaz — Sat, 02 May 2026 23:53:36 +0000

You know this feeling:

You open a new repository, read the README, click five files, open the wrong folder, find a second entry point, and ten minutes later you still cannot answer a basic question:

What should I read first if I want the real shape of this codebase?

That is the moment spine is built for.

spine is a small onboarding tool that scans a repository, finds a verified architecture spine, and turns it into something a developer can actually use:

a compact architecture map
a prioritized reading order
a short mental model
subsystem summaries
a few gotchas

The important part is not that it looks smart. The important part is that it stays grounded.

spine only draws architecture edges it can verify from source.
GitHub:

https://github.com/ahmedbutt2015/spine

Why Claude Code users should care

If you are already living inside Claude Code, spine is not just a documentation tool. It is a context tool.

The first run does two useful things:

it generates ONBOARDING.md for a human-readable tour
it writes .claude/REPO_CONTEXT.md, a compact repo snapshot for future Claude sessions

That second file matters a lot.

Instead of re-explaining the repo every time, you get a persisted summary of:

project shape
primary language
verified architecture spine
subsystem boundaries
key entry points

So the value is not only "help me understand the codebase once."

It is also:

help future Claude sessions start from a grounded snapshot instead of burning tokens rediscovering the same repo shape.

That does not mean Claude magically knows every line of the application forever. It means spine leaves behind a small verified context file that is useful to refresh and reuse as the repo evolves.

It is designed to feel instant inside Claude Code

The repo already ships with Claude Code skill definitions for:

/map
/onboard

That means the product story is simple:

Run /map when you want a fast, token-light architecture preview.
Run /onboard when you want the full guided tour.
Let spine refresh .claude/REPO_CONTEXT.md so later Claude sessions start from a much better baseline.

For teams using Claude Code heavily, this is one of the most interesting parts of the product.

You are not just generating a document. You are creating a reusable repo memory.

The problem with most onboarding docs

Most repo onboarding today breaks in one of three ways:

it is too broad and turns into a wall of context
it is stale and no longer matches the code
it sounds confident while quietly guessing the architecture

That last one is the worst.

If a diagram is wrong, it does not just waste time. It gives you the wrong mental model, and you end up reading the code in the wrong order.

spine takes a narrower bet:

smaller, verified, and useful beats bigger, prettier, and guessed.

What spine actually gives you

There are two modes.

`/map`

Use this when you want the fastest answer possible.

It gives you:

a validated Mermaid diagram
a mermaid.live link
no synthesis step
no ONBOARDING.md

This is the "show me the real backbone first" mode.

`/onboard`

Use this when you want the full tour.

It writes an onboarding document with:

TL;DR
Architecture map
Mental model
Reading order
Entry points found
Subsystems
Gotchas

This is the "I just joined this codebase, help me become dangerous fast" mode.

Try it in 3 minutes

If you want the best first impression, use axios.

It is the best launch example because:

most developers already know what it is
the repo is real but not huge
the request flow is meaningful
the output is easy to judge with your own eyes

Install:

npm install -g @spine-io/onboard

Clone a benchmark:

git clone https://github.com/axios/axios.git
cd axios

Start with the map:

onboard . --map-only

Then generate the full guide:

onboard .

That is the core experience.

If you are already in Claude Code, the equivalent mental model is:

/map      -> show me the verified backbone
/onboard  -> write the full guide and refresh repo context

What makes the first run feel good

The first useful moment is not a giant report. It is a reduction in ambiguity.

When spine works well, you feel three things quickly:

You can see the real entry path instead of guessing it.
You know which files matter first.
You can ignore the rest for now without feeling lost.

That is a very different experience from skimming a file tree and hoping your intuition is right.

Why axios is such a good demo

Before spine, a developer usually bounces around files like:

README.md
package.json
index.js
lib/axios.js
lib/core/Axios.js

That is not terrible, but it is not guided either. You are still doing the work of building the map in your head.

After spine, the repo gets compressed into a much more actionable shape:

a small verified graph
a short list of files to read first
a sentence or two that gives you the right mental frame

That is the whole product idea in one repo.

If someone asks what spine does, the shortest honest answer is:

It shows you where to start in a codebase, and it only draws the edges it can prove.

The part I care about most

I did not want to build another tool that generates a beautiful but suspicious diagram.

So the rule is simple:

if an edge can be verified, keep it
if it cannot be verified, drop it

That means the diagram is sometimes smaller than what a human might infer.

Good.

Smaller and true is better than bigger and imagined.

Why this can save tokens over time

There are really two savings stories here.

The first is human:

less random file clicking
less repeated explanation across teammates
less time building the wrong mental model

The second is model-side:

spine writes .claude/REPO_CONTEXT.md by default
the Anthropic synthesis path supports prompt caching on the structured context block
the CLI surfaces estimated cost and actual cost when usage metadata is available

So if you keep re-running onboarding in the same repo, or keep revisiting the same codebase with Claude, the product is trying to make those later passes cheaper and more grounded than the first one.

Claude Code is a natural fit

spine is also shaped to work well with Claude Code.

The flow is simple:

run /map when you want a fast architecture preview
run /onboard when you want the full guide
let .claude/REPO_CONTEXT.md carry verified context into later conversations

So instead of starting every coding session from scratch, you can start from a verified repo summary.

That is probably the most compelling long-run use case:

not "generate one nice markdown file,"

but "leave behind a compact, refreshable repo context file that helps Claude spend less time relearning the same app."

A fun way to try it

If you want to make this feel more interactive, try this little challenge:

Open a repo you know only vaguely.
Before running spine, write down which file you think is the true entry point.
Run onboard . --map-only.
See whether the verified spine agrees with your guess.
Then run onboard . and compare your reading order with the one it generates.

That turns the tool into a quick test of your own codebase intuition, which is honestly a fun way to experience it.

Where to use it next

After axios, I would try these:

glow for a clean Go CLI example
poetry for a larger Python repo
log for a compact Rust library
your own codebase right before onboarding a teammate

The most interesting use case is not a benchmark repo.

It is the repository where your team keeps saying, "someone should really document how this thing is wired."

Why this matters

The cost of a strange codebase is not just time. It is hesitation.

You do not know what to trust yet.
You do not know what is core versus incidental.
You do not know whether the architecture in your head is real.

spine is an attempt to reduce that hesitation.

Not by telling you everything.

By helping you start in the right place.

That is v1.

We Wrapped an Open-Source Agent in GraphOS and Turned the Debugging Session Into a Story

Ahmed Fayyaz — Sun, 26 Apr 2026 02:06:44 +0000

A story-driven, hands-on report about taking an existing open-source LangGraph.js agent, wrapping it in GraphOS, and learning what observability actually feels like when an agent goes sideways.

There is a moment every agent project eventually reaches.

The demo works. The graph looks clean. The tools are wired up. The prompt feels smart.

And then one run goes sideways.

Not in a dramatic, movie-scene way. In the real way.

The assistant calls the same tool again. Then again. The state grows. The trace gets noisier. The budget keeps moving in one direction. And the hardest part is not even the cost. It is the feeling that you can no longer see the system clearly.

That is the moment GraphOS was built for.

This post is not just a feature announcement. It is a field report. We took a real open-source project, wrapped it with GraphOS, ran the integration end to end, and used that exercise to answer one question:

Can an existing LangGraph.js agent — one we did not write — be made easier to observe, safer to run, and easier to explain to other developers?

The short answer is yes.

The better answer is the story below.

▶ Watch GraphOS catch a runaway agent loop (12s)

Before and after, in one breath

Before wrapping the agent in GraphOS:

Every run was a black box. The first signal that something was wrong was the OpenAI bill or a stuck UI.
Loops only surfaced as "this got slow" or "this never finished."
Debugging meant reading log files after the fact and reconstructing a sequence the system had not preserved.

After wrapping the agent in GraphOS:

Every step of the graph was observable in real time.
A loop was caught at visit 7, not visit 700.
A budget ceiling halted a misbehaving run before the credit card did.
Every past session became time-travelable in a local SQLite-backed dashboard, no SaaS in the loop.

Same agent. Same model. Different blast radius.

The benchmark we chose

Instead of inventing a toy example, we used an existing open-source benchmark:

agents-from-scratch-ts: https://github.com/langchain-ai/agents-from-scratch-ts

Inside this repository, that benchmark lives at:

benchmarks/agents-from-scratch-ts

It is a strong test case because it is not a toy. It already contains:

A working email assistant
A Human-in-the-Loop flow
A memory-enabled variant
Jest-based test suites
LangGraph wiring that looks like real application code, not a demo built for a tool launch

That makes it the right kind of pressure test for GraphOS. We did not want to ship a wrapper that only works on our own handcrafted demo. We wanted something that survives contact with someone else's architecture, state shape, tool conventions, and tests.

Why this matters

If you are reading this as a builder, imagine two options:

Build a brand-new sample agent designed to make the tool look good.
Take someone else's open-source agent and prove the tool against that.

We picked option 2.

That choice changes the tone of the work. Now the question is not "can GraphOS run a demo we wrote?" It becomes "can GraphOS survive contact with someone else's code?"

That is a much better story to tell — and a much better thing to ship.

What GraphOS adds to a graph

GraphOS is an observability and policy layer for LangGraph.js agents.

At a high level, it gives you three things:

A wrapper around any compiled graph
Composable policies (LoopGuard, BudgetGuard, more)
A local dashboard that shows what the agent did, step by step, and lets you scrub through past runs

The integration stays intentionally small:

import {
  GraphOS,
  LoopGuard,
  BudgetGuard,
  tokenCost,
  createWebSocketTransport,
} from "@graphos-io/sdk";

const managed = GraphOS.wrap(myCompiledGraph, {
  projectId: "my-agent",
  policies: [
    new LoopGuard({ mode: "node", maxRepeats: 10 }),
    new BudgetGuard({ usdLimit: 2.0, cost: tokenCost() }),
  ],
  onTrace: createWebSocketTransport(),
});

That is the promise. But promises are cheap.

So we tested it against the benchmark.

How we brought GraphOS into the benchmark

There are two installation stories worth separating, because people often confuse "how we developed it inside the monorepo" with "how I should use it in my own codebase."

Story 1: how we integrated it inside this monorepo

Because the benchmark is checked into this repository, the local integration uses the built SDK directly:

import {
  GraphOS,
  LoopGuard,
  BudgetGuard,
  tokenCost,
  createWebSocketTransport,
  PolicyViolationError,
} from "../../packages/sdk/dist/index.js";

That exact integration lives in:

benchmarks/agents-from-scratch-ts/graphos-wrap.ts

This is useful for development because it lets us iterate on GraphOS and immediately retest it against the benchmark without publishing a new package every time.

Story 2: how you would install it in any outside project

If you are doing this in your own LangGraph.js project, the install is the simple part:

npm install @graphos-io/sdk
# or
pnpm add @graphos-io/sdk

Then replace the local import with the published package import:

import {
  GraphOS,
  LoopGuard,
  BudgetGuard,
  tokenCost,
  createWebSocketTransport,
  PolicyViolationError,
} from "@graphos-io/sdk";

Same code, same wrapper. The only thing that changes is where the SDK comes from.

The wrapper we added

Here is the part of the benchmark integration that mattered:

const managed = GraphOS.wrap(graph, {
  projectId: "agents-from-scratch",
  policies: [
    new LoopGuard({ mode: "node", maxRepeats: 6 }),
    new BudgetGuard({
      usdLimit: 0.5,
      cost: tokenCost({ fallback: 0.05 }),
    }),
  ],
  onTrace: createWebSocketTransport(),
});

Three details deserve a beat each.

1. We used `LoopGuard` in `node` mode

This benchmark is exactly why node mode exists.

In many real agents, the state changes every iteration because the messages array keeps growing. That means pure state-equality is not enough to detect a loop. The graph may be functionally stuck even though the raw state object is technically different each turn.

So instead of asking:

"Did we revisit the exact same state?"

we ask:

"Did we keep revisiting the same node too many times?"

That is the more practical safety rule for agents that keep appending messages as they reason.

2. We set a budget ceiling

BudgetGuard lets us cap cumulative spend per session.

new BudgetGuard({
  usdLimit: 0.5,
  cost: tokenCost({ fallback: 0.05 }),
})

tokenCost() is a drop-in cost extractor that walks the state for LangChain messages, pulls usage from usage_metadata / response_metadata.usage / tokenUsage, and applies a built-in OpenAI + Anthropic price table. For unknown models you can pass a fallback (flat USD per step or a custom price entry).

This is not just observability anymore. The run has a real boundary.

3. We streamed telemetry to the local dashboard

This line is small:

onTrace: createWebSocketTransport()

But it changes the experience completely. Instead of waiting for the final output and guessing what happened, you watch the run unfold — node by node — in the GraphOS dashboard.

The small but clever trick: a mock key path

One of the nicest touches in the integration is that graphos-wrap.ts checks whether OPENAI_API_KEY starts with sk-mock. If it does, it installs a fetch interceptor and simulates the OpenAI responses.

Why is that useful?

Because it gives us a reproducible benchmark run that is intentionally shaped to trigger the loop path. In the mock flow:

The triage step routes the email into the response subgraph
The agent keeps requesting schedule_meeting
The graph cycles through llm_call ↔ environment
LoopGuard halts at visit 7 with a clean policy reason

That is the kind of test harness you want when you are building safety infrastructure. You do not want to rely on "hopefully the model misbehaves today." You want a deterministic failure mode you can use on purpose.

Reproduce the setup

If you want to walk through this yourself, the full path is short.

1. Install the workspace

From the repository root:

pnpm install

2. Build the SDK

pnpm --filter @graphos-io/sdk build

3. Move into the benchmark

cd benchmarks/agents-from-scratch-ts

4. Use the benchmark normally

The upstream benchmark documents its own workflow:

pnpm agent

It expects a .env file with your API key if you want real model calls:

OPENAI_API_KEY=your_api_key_here

5. Run GraphOS alongside it

In another terminal, start the dashboard:

npx @graphos-io/dashboard graphos dashboard
# open http://localhost:4000

Then run the wrapped benchmark entrypoint:

OPENAI_API_KEY=sk-mock pnpm exec tsx graphos-wrap.ts

To run against a real provider instead of the mock path, swap in a real key and keep the same wrapper.

What we actually verified

This is where the story becomes more than marketing. We did not just wrap the benchmark and eyeball the result.

GraphOS SDK verification

From the repo root:

pnpm --filter @graphos-io/sdk test

All SDK tests pass. Coverage spans:

LoopGuard — both state and node modes
BudgetGuard — cumulative cost ceiling
tokenCost() — multiple LangChain message shapes, multiple price-table lookups
GraphOS.wrap() — session lifecycle, error handling, sessionId continuity, listener-throw resilience

Benchmark verification

From benchmarks/agents-from-scratch-ts, the benchmark's own Jest suites still pass:

pnpm test:base
pnpm test:hitl
pnpm test:memory

That matters because it tells us something subtle but important:

GraphOS was developed alongside the benchmark without breaking the benchmark's behavior. We are not telling a story about observability by quietly degrading the agent underneath it.

What the benchmark actually exercises

This part is worth slowing down for. The benchmark is not one narrow happy path. It exercises:

Response quality
Expected tool calls
Human acceptance flow
Human edit flow
Human rejection with feedback
Memory persistence across later runs

So when we say we used agents-from-scratch-ts, we mean we used a compact but meaningful open-source application with real behavioral coverage — not "we ran one prompt once."

The human lesson

The benchmark is an email assistant, but the lesson is bigger than email.

Every agent team eventually needs answers to these questions:

What node did we get stuck in?
How many times did we visit it?
What tool calls were made before failure?
What did the state look like at that moment?
Was the run expensive because it was useful, or expensive because it was looping?

Without observability, those questions become archaeology.

With GraphOS, they become part of the normal debugging workflow.

A quick interactive moment

Imagine you are looking at a run and you see the same node lighting up over and over. Which of these do you want next?

A bigger console log
The final model output only
A live graph, a session timeline, and a policy halt reason that says exactly which guard fired and why

That is the difference this project is trying to create. Not more noise. Better visibility.

Why this story is stronger than a basic product post

The first version of a launch blog usually says:

Here is what we built
Here is the API
Here is why it is useful

That is fine, but it is mostly a claim.

This story is better because it shows:

The open-source project we used
The exact link to it
Where it lives in our repo
How we installed GraphOS into the workflow
How we wrapped the graph
How we tested both the SDK and the benchmark
What safety behavior we specifically cared about

In other words, this is not just what GraphOS is. It is how GraphOS behaves when it meets a real agent.

The files behind this story

If you want to inspect the exact pieces mentioned above, start here:

GraphOS root: README.md
Companion launch reference: docs/blog/v1-launch.md
Benchmark wrapper: benchmarks/agents-from-scratch-ts/graphos-wrap.ts
Benchmark package setup: benchmarks/agents-from-scratch-ts/package.json
Benchmark tests: benchmarks/agents-from-scratch-ts/tests

Final takeaway

GraphOS becomes much easier to understand when you stop describing it as a package and start describing it as a moment in a developer's day.

An agent starts drifting.

A team needs answers.

A wrapper adds policies.

A dashboard turns hidden execution into something visible.

A benchmark proves the idea against real code.

That is the story. And that is why we used agents-from-scratch-ts.

If you want to try the same path yourself:

Benchmark: https://github.com/langchain-ai/agents-from-scratch-ts
GraphOS: https://github.com/ahmedbutt2015/graphos
SDK on npm: https://www.npmjs.com/package/@graphos-io/sdk
Dashboard on npm: https://www.npmjs.com/package/@graphos-io/dashboard

npm install @graphos-io/sdk
npx @graphos-io/dashboard graphos dashboard

The next step is simple: wrap your graph, run your tests, and see what your agent was actually doing when nobody was watching.

Forem: Ahmed Fayyaz

Spine v1: Stop Making Claude Rediscover Your Codebase Every Time You Open a Repo

Why Claude Code users should care

It is designed to feel instant inside Claude Code

The problem with most onboarding docs

What spine actually gives you

/map

/onboard

Try it in 3 minutes

What makes the first run feel good

Why axios is such a good demo

The part I care about most

Why this can save tokens over time

Claude Code is a natural fit

A fun way to try it

Where to use it next

Why this matters

We Wrapped an Open-Source Agent in GraphOS and Turned the Debugging Session Into a Story

A story-driven, hands-on report about taking an existing open-source LangGraph.js agent, wrapping it in GraphOS, and learning what observability actually feels like when an agent goes sideways.

Before and after, in one breath

The benchmark we chose

Why this matters

What GraphOS adds to a graph

How we brought GraphOS into the benchmark

Story 1: how we integrated it inside this monorepo

Story 2: how you would install it in any outside project

The wrapper we added

1. We used LoopGuard in node mode

2. We set a budget ceiling

3. We streamed telemetry to the local dashboard

The small but clever trick: a mock key path

Reproduce the setup

1. Install the workspace

2. Build the SDK

3. Move into the benchmark

4. Use the benchmark normally

5. Run GraphOS alongside it

What we actually verified

GraphOS SDK verification

Benchmark verification

What the benchmark actually exercises

The human lesson

A quick interactive moment

Why this story is stronger than a basic product post

The files behind this story

Final takeaway

`/map`

`/onboard`

1. We used `LoopGuard` in `node` mode