tibo.

Tibo documentation · 10 minute read

Review what your coding agent decided.

This is the complete practical guide to Tibo. Start with the quick scan, learn how to read evidence, then add the review skill to Codex or Claude so every agent task leaves a clear decision trail.

Start the guideView source on GitHub ↗
01Understand the loop02Read a finding03Connect an agent

01 · Quick start

Use Tibo in the repository your agent just changed.

Tibo is a CLI. It does not need an account, API key, hosted workspace, or model call. It reads tracked and untracked working-tree changes locally.

# From your changed repository
npx --yes @goankan/tibo@0.1.1 scan

# Ask for stable JSON instead
npx --yes @goankan/tibo@0.1.1 scan --json

Input

Git diff plus untracked files

Output

Evidence-backed findings

State

A local decision ledger

02 · Mental model

Tibo is a checkpoint after the agent, before the decision disappears.

The core is deliberately boring and explainable. A Git change goes through narrow structural detectors. Each detector returns evidence, confidence, and a limitation. You decide. The ledger gives the next session the answer.

agent changes files ↓ Git working tree ↓ diff and line normalizer ↓ structural detectors ↓ evidence-backed findings ↓ you choose keep / reject / later ↓ .tibo/decisions.json + decisions.md ↓ next session runs npx --yes @goankan/tibo@0.1.1 summary

The host agent can explain returned evidence and make an explicitly approved repair. Tibo itself never edits source files and never silently approves a finding.

03 · Supported changes

What Tibo can detect today

The first release focuses on TypeScript and JavaScript repositories. The output is intentionally smaller than a generic linter.

01

@supabase/supabase-js ^2.0.0

Dependency

New manifest entries, requested versions, added import or load sites, and possible repository matches.

02

NEXT_PUBLIC_SUPABASE_URL

Environment

New process.env reads using dot or bracket notation, with the file that reads the value.

03

DROP COLUMN email

Schema

SQL and migration changes, including a high-severity marker for potentially destructive operations.

04

export type Session = ...

Interface

New or changed exported functions, classes, constants, types, and interfaces.

05

src/utils/mail.ts

Module

Possible overlap for a newly added file using bounded filename and symbol evidence.

Possible matches are lexical evidence, not proof that two packages or modules are equivalent. Tibo says what it found and what it cannot know from a diff.

04 · Read a finding

Evidence first. Story second.

Every finding answers four questions: what changed, where it changed, why Tibo raised it, and what remains unknown.

{
  "id": "8a2a693714dd",
  "kind": "dependency",
  "summary": "dependency added  @supabase/supabase-js ^2.0.0",
  "evidence": [
    {
      "path": "package.json",
      "detail": "Added manifest entry: @supabase/supabase-js"
    },
    {
      "path": "src/lib/supabase.ts",
      "line": 2,
      "detail": "Added import"
    }
  ],
  "confidence": "high",
  "limitation": "Presence in a manifest does not prove necessity or safety.",
  "decision": "unreviewed"
}

Evidence

Paths and lines you can open and verify.

Limitation

The boundary between a signal and a conclusion.

05 · Before and after

A review becomes useful when it names the decision.

A package name alone creates suspicion. Evidence gives an engineer something concrete to approve, reject, or defer.

Before · vague review

“The agent added Supabase. Is that okay?”
  • • No version
  • • No import location
  • • No indication of existing alternatives
  • • No durable answer for the next session

After · Tibo review

“@supabase/supabase-js ^2.0.0 was added to package.json and imported in src/lib/supabase.ts:2. Keep, reject, or later?”
  • • Exact package and requested version
  • • Evidence paths and line numbers
  • • Confidence and limitation
  • • Decision stored in the ledger

06 · Everyday workflow

Four commands cover the loop.

Install and scan

npx --yes @goankan/tibo@0.1.1 scan

Run from the repository the agent changed.

Machine output

npx --yes @goankan/tibo@0.1.1 scan --json

Give stable findings to an agent, script, or CI job.

Record a decision

npx --yes @goankan/tibo@0.1.1 decide <id> keep|reject|later

Store only the human's explicit choice.

Show project memory

npx --yes @goankan/tibo@0.1.1 summary --json

Give the next agent the ledger and unresolved findings.

If you are working from a checkout instead of npm, build with npm run build and use node dist/index.js in place of npx --yes @goankan/tibo@0.1.1.

07 · Decisions and ledger

Rejecting records intent. It does not delete code.

Keep means you accepted the decision. Reject means you do not want to approve it. Later leaves the question visible. None of these commands edits the repository.

npx --yes @goankan/tibo@0.1.1 decide 8a2a693714dd reject
npx --yes @goankan/tibo@0.1.1 summary --json
# Tibo decisions

## 8a2a693714dd · dependency
- decision: keep
- subject: @supabase/supabase-js ^2.0.0
- evidence: package.json:12, src/lib/supabase.ts:2
- decided: 2026-09-22

The JSON ledger is stored at .tibo/decisions.json. The Markdown view at .tibo/decisions.md is for humans and future agent sessions. Stable finding IDs stop the same decision from being asked again without a meaningful change.

08 · Codex and Claude

Give an AI agent a safe review contract.

Tibo includes a portable skill at skills/tibo-review/SKILL.md. Copy it into Codex or Claude Code. The host agent explains returned evidence and asks for your decision; Tibo remains the source of truth.

Codex

mkdir -p ~/.codex/skills/tibo-review
cp -R skills/tibo-review/* \
  ~/.codex/skills/tibo-review/

Claude Code

mkdir -p .claude/skills/tibo-review
cp -R skills/tibo-review/* \
  .claude/skills/tibo-review/

The host-agent contract

  1. 1.Run npx --yes @goankan/tibo@0.1.1 scan --json after the agent changes files.
  2. 2.Show each summary, evidence path, confidence, and limitation.
  3. 3.Ask the human for keep, reject, or later. Never choose silently.
  4. 4.Record the explicit answer with npx --yes @goankan/tibo@0.1.1 decide.
  5. 5.Only after separate approval, make a narrow repair, test it, and scan again.

09 · Best practices

Keep the review small enough to trust.

Run at the boundary

Scan when an agent says a task is complete and before you commit. The context is fresh and the diff is still easy to understand.

Treat evidence as a prompt

Open the referenced file and line. A finding tells you where to look; it does not replace engineering judgment.

Use later instead of guessing

If you need product context, defer the finding. Do not accept a choice just to clear the inbox.

Keep the ledger reviewable

Record the reason in the surrounding project context when a choice matters. Reset an entry intentionally instead of deleting history casually.

10 · Boundaries

What Tibo does not claim.

  • It does not read your repository with a model.
  • It does not prove that a dependency is necessary or safe.
  • It does not understand product intent from a diff alone.
  • It does not replace tests, code review, or architectural judgment.
  • It does not edit files when you reject a finding.
  • It does not send repository contents to a hosted service.

11 · Roadmap

What comes next is evidence, not more noise.

The roadmap is intentionally staged. Next are richer route, event, serialized-field, module-graph, and rollback detectors; real Codex and Claude validation; team review surfaces; and an optional evidence-only explanation provider.

Read the full roadmap ↗View the timeline ↗Read architecture ↗

FAQ

Common questions

Does Tibo need OpenAI, OpenRouter, or another model?+

No. Detection is local and deterministic. The Codex or Claude skill can explain the returned evidence, but Tibo does not require a model call.

Will reject remove the code?+

No. Reject only records your decision. A host agent can make a repair only after you separately approve that repair plan.

Does it work with untracked files?+

Yes. Tibo includes untracked files in the local scan so a newly created file can be reviewed before it is staged.

What languages are supported?+

The first release focuses on TypeScript and JavaScript repositories and their common manifests, environment reads, migrations, and exports.

Where does the history live?+

In .tibo/decisions.json and .tibo/decisions.md inside the repository. There is no hosted account or required dashboard.

+