Skip to content

Getting started

What is Wisdom?

An open-source recorder for coding agents, and the way you and your agents read what it recorded.

Wisdom records your coding agent’s sessions on your own machine: what you asked, what the agent ran, which files it changed, and what it said it did. You read those sessions in the terminal or a local dashboard, and your agents read them through a skill, so the next agent starts from what actually happened.

It works with:

Terminal
npm install -g @oqura/wisdom # Node.js 24 or newer
cd your-project
wisdom connect # then start your agent here as usual

That’s the whole setup. Quick start walks through it and reads your first session back.

  • Review an agent’s work against the request behind it, not only against its final reply.
  • See the test that failed before the fix, and the approach the agent tried and dropped.
  • Hand unfinished work to another agent, even a different one, that reads the session first.
  • Review a teammate’s pull request with the session behind each commit, in team mode.
  • Find the session behind a change weeks later, starting from its commit, from the terminal or from any agent.

A diff shows what changed. The session shows why, and it’s gone once the terminal closes unless something records it.

How Wisdom works: Claude Code and Codex send events through hooks, and Pi through an extension, to a local daemon on 127.0.0.1 that never blocks the agent. It saves them in the project’s .wisdom folder: SQLite, diffs and transcript copies. At each commit, Wisdom keeps a record in your repository’s .git that links each change to the step that made it. The dashboard, the CLI (glance, open, glance –commit) and the agent skill read it. In team mode, which is opt-in, git push sends records and sessions to your own git remote for teammates and CI.

  1. Your agent’s own hooks send each event (a prompt, a tool call, its result) to a small background service on 127.0.0.1.
  2. The service saves it in the project’s .wisdom/ folder, together with a byte-for-byte copy of the agent’s transcript and a diff of every file change it observed.
  3. You read it in the dashboard or the terminal. Your agents read it through a skill Wisdom gives them.
  4. When you commit, Wisdom keeps a record in your repository’s .git that links each change to the step that made it. In team mode, your git push shares those records and their sessions with your team.

More detail in How it works.

For coding agents, these docs are also published as plain text: llms.txt is the index, and llms-full.txt has every page in one file.

Does it slow down my agent?

Each hook sends one request to a service on your own machine. If the service doesn’t answer, the hook writes the event to disk and the agent carries on. Wisdom never blocks your agent.

Does it send my code or prompts anywhere?

No. Everything stays in the project’s .wisdom/ folder. A recording leaves your machine only when you run wisdom share or wisdom export, or push in team mode, which you turn on per repository. All of them check for secrets first. See Privacy.

Does it use a model, or cost tokens?

Recording uses no model and costs nothing. Nothing is summarized. When one of your agents reads a session, that reading counts toward your agent’s own usage, like any other command output.

The one place a model writes anything is a commit guide, and only when you ask for one or turn on team mode. By default it runs through your own Claude Code.

Do I need to change how I start my agent?

No. After wisdom connect, you start claude, codex or pi as usual, with your own login. See Record sessions for the one rule each agent has.

Does it change my global agent settings?

No. Wisdom never edits ~/.claude, ~/.codex or ~/.pi/agent. It writes only to the project’s own settings, keeps them out of git, and wisdom disconnect removes exactly that.