Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add skills/konghayao/peri/codebase-indexnpx skills add KonghaYao/peri --skill codebase-indexgit clone --depth 1 https://github.com/KonghaYao/periWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00155 | $0.01506 |
| Opus 5 | $0.00077 | $0.00753 |
| Sonnet 5 | $0.00031 | $0.00301 |
| Haiku 4.5 | $0.00015 | $0.00151 |
Grade A, and why
codebase-index scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 80 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Codebase Index
索引是什么
- 位置：
docs/code-index/<crate>.md，跨模块链路在docs/code-index/cross-crate.md - 本质：行为 → 文件 的速查表。查询者带着「我想改 X 的 Y」进来，带着文件路径和入口函数出去
- 原则：只给定位信息 + 一句话关键逻辑；不解释原理、不复制规范正文、不替代设计文档
- 体积：每个文件 100–200 行，全部读入没有负担。索引存在的意义就是让"找文件"这一步从几十次搜索变成一次读表
查找流程（查询者视角，最常用）
- 判断行为落在哪个 crate；不确定就 Glob
docs/code-index/*.md并全部读入 - 在速查表里按行为关键词匹配条目（compact / keepgoing / is_direct / cancel / middleware / prompt …）
- 打开主文件，跳转到入口函数
- 索引里的一句话关键逻辑只用于导航；行为细节一律以代码为准
- 跨模块链路看各索引的「跨模块契约」节或 cross-crate.md，那里指向
docs/standards/architecture-contracts.md的 ARC 编号（不复制正文）
构建/更新流程（构建者视角）
触发时机：索引缺失、行为变更后索引过期、用户要求重建/扩充。
输入：目标 crate 源码 + 该 crate 的 CLAUDE.md + docs/standards/architecture-contracts.md（跨模块契约）+ 相关 docs/design/ 文档 + spec/issues/ 中最近的相关 issue。
步骤：
- 读 crate 的
CLAUDE.md，Scope / 数据流 / 稳定不变量直接进「架构速览」 - 用 Grep 验证每个文件路径、函数名、常量真实存在（记行号）；禁止凭记忆写路径
- 逐子系统列条目；每条覆盖：功能 | 文件 | 入口/关键函数 | 一句话关键逻辑
- 关键逻辑写行为契约（阈值、顺序、条件、边界），一句话讲清，不复制文档正文
- 标注事实源关系：
re-export/ 配置事实源 / 注册面要写清归属（例：compact_v2/config.rs仅 re-exportperi-acp-types::compact::CompactConfig，注册面是 middlewarecollect_tools()而非工具模块本体） - doc comment 与代码不一致时以代码为准（本仓库出现过 mod.rs 顶部 doc 描述的触发语义与实际判断条件不符），并在索引里写实际行为
- 跨 crate 链路（事件、cancel、工具可见性、prompt frozen 等）进「跨模块契约」节，指向 ARC 编号；涉及多个 crate 的链路同时在相关 crate 的索引里互相可见
- TUI / UI 类 crate 额外列「关键控件/组件」表（kit 组件、widget 等）
- 自检：每条路径存在、函数名存在、行为描述与代码一致
索引文件格式（当前 canonical，经两轮检索实验验证）
# <crate> 代码索引
> 速查表：把「我想做什么」映射到文件。细节以代码为准。更新：YYYY-MM-DD
> 依据：<crate>/CLAUDE.md、docs/standards/architecture-contracts.md、源码
## 架构速览
- 数据流 / 循环入口 / 稳定不变量（来自 crate CLAUDE.md）
## 速查表
| 我想做什么 | 主文件 | 入口/关键函数 | 关键逻辑 |
| --- | --- | --- | --- |
| （行为/修改意图，如"改 compact 触发阈值"） | （路径；事实源/re-export 关系标清） | （真实函数名 + 行号） | （一句话行为契约：阈值/顺序/条件） |
## 子系统
### <子系统名>
| 功能 | 文件 | 入口/关键点 |
| --- | --- | --- |
## 跨模块契约
- ARC-XXX-001：一句话要点 → `docs/standards/architecture-contracts.md`
实验结论（为什么是这个结构）：
- 「我想做什么」列直接匹配查询意图，subagent 检索时零推理成本命中（variant-b 模块卡片也准确但需自行提取，效率等价、推理略多）
- 每行带真实入口函数名 + 行号，检索者打开文件即可跳转，不必再全库搜函数
- 一句话行为契约（阈值/顺序/条件）让检索者先判断"这是不是我改的点"，再读代码
- 「跨模块契约」节 + ARC 编号指针足以支撑跨 crate 查询（事件链路等），无需复制契约正文
- 索引错误会被"以代码为准"验证兜住，但构建时写对（标注 re-export/事实源关系、doc 与代码冲突时信代码）能避免误导
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2d ago First seen · 80 lines · 155 tokens per session scan A f188ee087740
codebase-index is a skill published in the GitHub repository KonghaYao/peri (157 stars, last pushed 3d ago), licensed Apache-2.0. It adds 155 tokens to every session and 1,506 once invoked, about $0.0008 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other skills, from other repositories
qa-testing
Verify your work by actually operating the app or website you changed, instead of assuming it works. Strongly recommended whenever you build, modify, or debug a web app, website, or desktop GUI app. Drive real browsers with the agent-browser CLI and native desktop apps with the cua-driver CLI. These are installed on…
plugin-creator
Create and scaffold plugin directories for Codex with a required .codex-plugin/plugin.json, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries…
babysit-pr
Babysit a GitHub pull request after creation by continuously polling review comments, CI checks/workflow runs, and mergeability state until the PR is merged/closed or user help is required. Diagnose failures, retry likely flaky failures up to 3 times, auto-fix/push branch-related issues when appropriate, and keep…
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output…
skill-creator
Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.
codex-pr-body
Update the title and body of one or more pull requests.