Set up knowledge for a repo
Let EasyCode scan a repo and map your org's code, so every session can read how the repos fit together before it changes anything.
A session that only sees one folder misses how the org's repos fit together: which service publishes an event, who calls a route, where an env key is read. Knowledge gives every session in your org the whole picture. It works from the code itself, on your team's own machines and GitHub logins.
A module
Knowledge is a module. With it off, a product's Knowledge tab says "Knowledge is off for" your org, and only Overview shows until an admin turns it on.
What it does
There are three parts, and the first two need nothing from you once a repo is in a product.
- The scan. The desktop app reads each repo of your org's products and builds an index of its code facts: routes, client calls, events published and handled, queues, packages, scripts, env keys and symbols. Only names, paths, line numbers and one-line signatures go to EasyCode, never code bodies, and secret-shaped values are dropped. The scan reads the default branch from git. It never reads your working folder, and nothing is installed, built or run.
- The checkouts and the map. In an org space, the app keeps a read-only checkout of each repo, at the head of its
default branch. Beside them it writes the org map:
ORG.md, one line per repo with its products, a summary and its key paths, and theorg/*.tsvtables. Every row in a table ends in therepo/path:lineit came from. - Model-written knowledge. For each product, an admin can have a model propose its conventions and capture its design system. You review the result before it is published.
Before you start
- The repo is linked to a product. On a product with none, the tab says "Link a repo in the product settings to set up its knowledge"; an admin or a maintainer does that. See Products and repos.
- The GitHub App can see the repo.
- Someone on the team runs the desktop app and can read the repo on GitHub.
Let your computer scan
The scan runs on members' computers, through their own git login. In the desktop app, open Settings, then
Desktop, and turn on Scan repos on this computer: "When you can read a picked repo on GitHub, this computer reads
it and builds its index for the org." It's on by default (knowledge.scan). A computer scans at
most three repos at a time, and a repo is scanned by one computer at a time.
When a scan fails for the repo's own sake, such as a refused clone, EasyCode records the error on the repo.
What a session gets
When a session starts in an org space, its instructions carry a short "Org code" rule: every repo is checked out
read-only, and ORG.md maps the products and repos. Before changing files in a repo, the session reads that repo's
rows in the tables.
The map goes in whole while it fits. In a larger org the session gets its own product in full and one line for each
other repo, or one line per repo. The session's chip shows which: "Org map: full", "Org map: this product in full,
others one line" or "Org map: one line a repo". ORG.md itself always holds the whole map.
The tables are plain files a harness can grep:
| Table | What's in it |
|---|---|
org/repos.tsv | Each repo, its indexed commit and default branch |
org/products.tsv | Which repos make up each product, and their roles |
org/routes.tsv | HTTP routes, by method |
org/events.tsv | Events and topics, who publishes and who handles them |
org/env.tsv | Where each env key is read |
org/deps.tsv | Which repo depends on which, and how |
org/stack.tsv, org/components.tsv, org/commands.tsv | The stack, the components and the commands each repo runs |
org/agent-files.tsv | Each repo's own harness files, such as CLAUDE.md |
org/owners.tsv, org/submodules.tsv, org/design.tsv | Code owners, submodules and design systems, when there are any |
The harness reads the checkouts and the map with its own file tools, under its own permissions. There is no separate search tool to call.
Propose conventions and capture the design system
On a product, open the Knowledge tab. "Repos are scanned on their own. These two are written by a model on the assignee's computer, and you review the result before it is published."
Start the task
Press Propose conventions (the product's rules and standards, each with its evidence in the code) or Capture the design system (its tokens and components, read from its repos). Only admins and the product's maintainers start these. Assign the task to a member who can see the product and read its repos on GitHub.
Run it
The assignee opens the task and presses Start run. It runs in Claude Code or Codex on their machine, and shows to the team as an org session titled with the task. Retry resumes a failed stage on the same machine.
Review and publish
An approver opens the Result for approval, with its sections, evidence and provenance, and presses Approve and publish or Send back with what to change. A published result becomes a library asset that sessions load.
To have your computer take tasks assigned to you on its own, turn on Run my knowledge tasks in the background in
the desktop app's Desktop settings (knowledge.autoRefresh). Org admins set the review rule and
the model per harness under Settings, Knowledge.
Your org admin can stop knowledge runs with the knowledge switch. Setup and review still work.
Related
- Start a session: what else a session gets
- Bring your existing kit
- Design in every session
Something wrong or missing? Suggest a change