Katana — Toolkit de Plugins para Claude Code
Dandi007/katana
Toolkit de plugins modulares para pesquisa, memória e análise estruturada no Claude Code
Ver no GitHubSuite modular de plugins para Claude Code que adiciona capacidades avançadas como pesquisa profunda, gerenciamento de memória, análise de primeiros princípios e wiki mantida por IA. Cada plugin é independente e pode ser instalado conforme necessário, oferecendo convenções de pasta de trabalho, checkpoints entre sessões e recuperação de informações multi-fonte.
Instalação
npx convez-ai Dandi007/katana1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Pesquisa profunda com citações e relatórios estruturados
- Manutenção de base de conhecimento com wiki orientada por esquema
- Análise de primeiros princípios com validação adversarial
- Persistência de trabalho entre sessões com checkpoints
Veredito

Katana é uma suite engenhosamente estruturada para quem precisa de produtividade contextual avançada no Claude Code. Destaca-se pela modularidade, suporte a análise rigorosa (FPA com validação adversarial) e integração profunda com workflows de pesquisa — excelente para pesquisadores, construtores de conhecimento e analistas que exigem rastreabilidade e qualidade.
README
A tradução para o português deste README ainda está na fila.
katana
A sharp little toolkit of agent plugins. Each plugin is independently installable — take only what you need.
| Plugin | What it does |
|---|---|
guide | Toolkit map + composition guide (using-katana), injected at session start |
work-folder | Work-folder convention (injected each session) + checkpoint skill for cross-session save/resume |
deep-research | Workflow-orchestrated research over your knowledge base + web + named platform sources (declared in config); judgment-driven stop; cited report |
memory | Verified facts as memory cards, auto-injected as an L1 index each session |
obsidian-md | Obsidian Markdown writing rules grounded in official docs (obsidian-writing) — wikilinks, headings, frontmatter, embeds, callouts; every rule cites obsidian.md/help |
wiki | LLM-maintained wiki engine — schema-driven zones, provenance-enforced ingest, deterministic query ladder, adversarial lint (Karpathy pattern: compile not re-derive; governance: immutable raw, provenance, adversarial lint, human gate) |
retrieval | Multi-source information retrieval — intent→source routing, credibility ladder, fallback chains; web/reddit/twitter/code/github/gitlab/linear/feishu/search-note adapters |
fpa | First Principles Analysis — enforced four-step reasoning (deconstruct/challenge/reconstruct/validate) with adversarial Workflow verification, mechanical acceptance hooks (FPA-*.md structure + three-artifact suite), and an inline calibration skill (first-principles-thinking) |
Install (Claude Code)
/plugin marketplace add Dandi007/katana
/plugin install guide@katana
/plugin install work-folder@katana
/plugin install deep-research@katana
/plugin install memory@katana
/plugin install obsidian-md@katana
/plugin install wiki@katana
/plugin install retrieval@katana
/plugin install fpa@katana
Enable/disable any plugin independently with /plugin.
Install (OpenCode)
katana provides an OpenCode parity adapter that enables the same hook implementations to work on OpenCode. Install via npm:
opencode plugin opencode-katana
Or for development, add the local path to your opencode.json:
{
"plugin": ["/path/to/katana"]
}
The adapter maps OpenCode events to Claude Code hook semantics, spawning the
same plugins/*/hooks/* scripts. SessionStart hooks inject context (guide,
work-folder, retrieval, wiki), PostToolUse hooks validate FPA documents, and
all skills are exposed to OpenCode's skill discovery.
Configuration:
KATANA_PARITY_ROOT— override katana root path (default: auto-detect from adapter location)KATANA_DISABLED_PLUGINS— comma-separated list of plugins to disable (e.g.,wiki,retrieval)
Parity verification:
./parity/e2e/run.sh parity/e2e/scenarios/basic.json both
This runs the same scenario on both Claude Code and OpenCode, comparing injection parity (via ccs payload forensics), FPA validation triggers, and skill exposure.
Install (Codex)
SKILL.md files follow the Agent Skills open standard, which Codex supports natively (source: agentskills.io client listing, developers.openai.com/codex/skills).
Codex discovers skills from .agents/skills/ in your repo root (and parent
directories up to the repo root), as well as $HOME/.agents/skills for
user-level installs.
Project-level install (skills available in this repo only):
# Clone katana and symlink the skills you want into your repo's .agents/skills/
git clone https://github.com/Dandi007/katana /tmp/katana
mkdir -p .agents/skills
cp -r /tmp/katana/plugins/guide/skills/using-katana .agents/skills/
cp -r /tmp/katana/plugins/work-folder/skills/checkpoint .agents/skills/
cp -r /tmp/katana/plugins/deep-research/skills/deep-research .agents/skills/
cp -r /tmp/katana/plugins/memory/skills/remember .agents/skills/
cp -r /tmp/katana/plugins/memory/skills/validate .agents/skills/
cp -r /tmp/katana/plugins/obsidian-md/skills/obsidian-writing .agents/skills/
cp -r /tmp/katana/plugins/wiki/skills/using-wiki .agents/skills/
cp -r /tmp/katana/plugins/wiki/skills/init .agents/skills/
cp -r /tmp/katana/plugins/wiki/skills/ingest .agents/skills/
cp -r /tmp/katana/plugins/wiki/skills/query .agents/skills/
cp -r /tmp/katana/plugins/wiki/skills/lint .agents/skills/
cp -r /tmp/katana/plugins/fpa/skills/fpa .agents/skills/
cp -r /tmp/katana/plugins/fpa/skills/first-principles-thinking .agents/skills/
User-level install (skills available across all repos):
git clone https://github.com/Dandi007/katana /tmp/katana
mkdir -p "$HOME/.agents/skills"
cp -r /tmp/katana/plugins/guide/skills/using-katana "$HOME/.agents/skills/"
cp -r /tmp/katana/plugins/work-folder/skills/checkpoint "$HOME/.agents/skills/"
cp -r /tmp/katana/plugins/deep-research/skills/deep-research "$HOME/.agents/skills/"
cp -r /tmp/katana/plugins/memory/skills/remember "$HOME/.agents/skills/"
cp -r /tmp/katana/plugins/memory/skills/validate "$HOME/.agents/skills/"
cp -r /tmp/katana/plugins/obsidian-md/skills/obsidian-writing "$HOME/.agents/skills/"
cp -r /tmp/katana/plugins/wiki/skills/using-wiki "$HOME/.agents/skills/"
cp -r /tmp/katana/plugins/wiki/skills/init "$HOME/.agents/skills/"
cp -r /tmp/katana/plugins/wiki/skills/ingest "$HOME/.agents/skills/"
cp -r /tmp/katana/plugins/wiki/skills/query "$HOME/.agents/skills/"
cp -r /tmp/katana/plugins/wiki/skills/lint "$HOME/.agents/skills/"
cp -r /tmp/katana/plugins/fpa/skills/fpa "$HOME/.agents/skills/"
cp -r /tmp/katana/plugins/fpa/skills/first-principles-thinking "$HOME/.agents/skills/"
Testing
Skills are regression-tested by contract: each skill declares an explicit
contract (input prompt + mechanical artifact assertions), executed for real
via claude -p in an isolated fixture KB with per-case snapshots. A judge
layer backstops semantic expectations (NEEDS-REVIEW, never hard-fail). See
tests/README.md.
Claude Code-specific features degrade gracefully elsewhere:
guide/work-foldercontext injection andmemoryindex injection use Claude Code SessionStart hooks. On Codex, paste the work-folder convention (plugins/work-folder/rules/work-folder.md) into your project's AGENTS.md.wikizone-index injection uses a Claude Code SessionStart hook. On other tools, pass the index path viaWIKI_INDEXenv var or setwiki.index_pathin your.katanafile.deep-researchorchestration uses Claude Code's Workflow tool; other tools can follow the SKILL.md flow manually.fpamechanical acceptance uses a Claude Code PostToolUse hook and its adversarial verification uses the Workflow tool. On other tools, runpython3 skills/fpa/scripts/validate_fpa.py <file>manually and dispatch skeptic subagents per the SKILL.md prompts.
Configuration
Katana plugins support three-tier configuration (highest priority first):
- Environment variables — machine-level overrides
.katanafile — project-level configuration (committed to repo)- Default values — sensible defaults for most projects
.katana file
Create a .katana file in your project root to customize plugin behavior:
# Katana plugin configuration
# Priority: environment variables > this file > plugin defaults
# work-folder: override the default work folder path
work_folder_path=智元工作/工作记录
# memory: override the project memory directory
memory_project_dir=memory
# deep-research: override the knowledge base root directory
deep_research_kb_dir=.
# deep-research: named platform sources (name:entry pairs) and fan-out width
deep_research_sources=feishu:.agents/skills/lark-cli/SKILL.md,gitlab:.agents/skills/gitlab/SKILL.md,github:gh
deep_research_max_width=10
The file uses simple key=value format. Lines starting with # are comments.
Configuration options
| Plugin | Key | Env var | Default | Description |
|---|---|---|---|---|
| work-folder | work_folder_path | KATANA_WORK_FOLDER | docs/work-records | Work folder base path |
| memory | memory_project_dir | CLAUDE_MEMORY_PROJECT_DIR | memory | Project memory directory |
| memory | — | CLAUDE_MEMORY_SYSTEM_DIR | ~/.claude/memory | System memory directory |
| deep-research | deep_research_kb_dir | DEEP_RESEARCH_KB_DIR | current directory | Knowledge base root |
| deep-research | deep_research_sources | DEEP_RESEARCH_SOURCES | (none) | Named sources, comma-separated name:entry |
| deep-research | deep_research_max_width | DEEP_RESEARCH_MAX_WIDTH | 10 | Max clues explored per round (fan-out width) |
| wiki | wiki_root | KATANA_WIKI_ROOT | wiki | Wiki knowledge base root directory |
Note: System-level memory directory only supports environment variables (machine dimension, not project-specific).
Version control: Commit .katana to share project config with your team. Use environment variables for machine-specific overrides (paths, credentials) that shouldn't be in the repo.
Example
For a Chinese knowledge base project:
# .katana
work_folder_path=智元工作/工作记录
memory_project_dir=memory
deep_research_kb_dir=.
deep_research_sources=feishu:.agents/skills/lark-cli/SKILL.md,gitlab:.agents/skills/gitlab/SKILL.md,github:gh
deep_research_max_width=10
This tells katana to use 智元工作/工作记录/YYYY/MM/DD/<topic>/ for work folders instead of the default docs/work-records/.... The deep_research_sources / deep_research_max_width entries declare named platform sources for deep-research workers and the per-round fan-out width.
memory scanner
On session start the memory hook (plugins/memory/hooks/session-start) scans the
memory card frontmatter with a pure shell + awk scanner
(plugins/memory/hooks/scan-memory.awk) and injects the <memory-index>. It is a
text script — no compiled binary, no download, no build step — so it ships intact
in the npm package and runs anywhere bash + awk exist. If no cards are found it
emits nothing (never blocks the session). Output is locked to a golden by
plugins/memory/tests/scan-memory.test.sh.
Releasing (maintainer)
- Bump
versionin the plugin'splugin.jsonandversionin the rootpackage.json. - Tag
v<version>and push;npm-publish.ymlpublishes the package and creates the GitHub Release.
License
MIT