convez.ai
AgenteProdutividadeIntermediário
Dandi007

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 GitHub
InicialPluginScore · de 0 a 100

Suite 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/katana

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
oc-v0.2.0
Issues abertas
27
Contribuidores
1

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.

PluginWhat it does
guideToolkit map + composition guide (using-katana), injected at session start
work-folderWork-folder convention (injected each session) + checkpoint skill for cross-session save/resume
deep-researchWorkflow-orchestrated research over your knowledge base + web + named platform sources (declared in config); judgment-driven stop; cited report
memoryVerified facts as memory cards, auto-injected as an L1 index each session
obsidian-mdObsidian Markdown writing rules grounded in official docs (obsidian-writing) — wikilinks, headings, frontmatter, embeds, callouts; every rule cites obsidian.md/help
wikiLLM-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)
retrievalMulti-source information retrieval — intent→source routing, credibility ladder, fallback chains; web/reddit/twitter/code/github/gitlab/linear/feishu/search-note adapters
fpaFirst 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-folder context injection and memory index 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.
  • wiki zone-index injection uses a Claude Code SessionStart hook. On other tools, pass the index path via WIKI_INDEX env var or set wiki.index_path in your .katana file.
  • deep-research orchestration uses Claude Code's Workflow tool; other tools can follow the SKILL.md flow manually.
  • fpa mechanical acceptance uses a Claude Code PostToolUse hook and its adversarial verification uses the Workflow tool. On other tools, run python3 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):

  1. Environment variables — machine-level overrides
  2. .katana file — project-level configuration (committed to repo)
  3. 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

PluginKeyEnv varDefaultDescription
work-folderwork_folder_pathKATANA_WORK_FOLDERdocs/work-recordsWork folder base path
memorymemory_project_dirCLAUDE_MEMORY_PROJECT_DIRmemoryProject memory directory
memory—CLAUDE_MEMORY_SYSTEM_DIR~/.claude/memorySystem memory directory
deep-researchdeep_research_kb_dirDEEP_RESEARCH_KB_DIRcurrent directoryKnowledge base root
deep-researchdeep_research_sourcesDEEP_RESEARCH_SOURCES(none)Named sources, comma-separated name:entry
deep-researchdeep_research_max_widthDEEP_RESEARCH_MAX_WIDTH10Max clues explored per round (fan-out width)
wikiwiki_rootKATANA_WIKI_ROOTwikiWiki 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)

  1. Bump version in the plugin's plugin.json and version in the root package.json.
  2. Tag v<version> and push; npm-publish.yml publishes the package and creates the GitHub Release.

License

MIT

Ver o original no GitHub

Bom para

Relacionados