mirror of
https://github.com/lucasrosati/claude-code-memory-setup.git
synced 2026-08-03 07:40:00 +02:00
fix: update outdated graphify CLI commands in setup guide (#6)
* docs: update installation and usage instructions for Graphify in README.md and README.pt-BR.md * docs: document both /graphify skill and headless CLI paths
This commit is contained in:
Abbass Jaber
@@ -318,36 +318,79 @@ Install the **"Export Claude Chat to Markdown"** browser extension for Chrome/Ed
|
||||
|
||||
```bash
|
||||
pip install graphifyy
|
||||
graphify install
|
||||
graphify install --platform claude
|
||||
```
|
||||
|
||||
`graphify install` creates the skill at `~/.claude/skills/graphify/SKILL.md`.
|
||||
`graphify install --platform claude` creates the skill at `~/.claude/skills/graphify/SKILL.md`. Other platforms are also supported (`cursor`, `codex`, `opencode`, etc.).
|
||||
|
||||
**1.5. Set up API key (required for semantic extraction):**
|
||||
|
||||
Graphify needs an LLM API key from Anthropic or Moonshot (Kimi) for semantic extraction. Export one before running:
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="your-key-here"
|
||||
# or
|
||||
export MOONSHOT_API_KEY="your-key-here"
|
||||
```
|
||||
|
||||
If you want to skip LLM costs entirely, use AST-only mode:
|
||||
|
||||
```bash
|
||||
graphify extract . --out ./graphify-out --no-cluster
|
||||
```
|
||||
|
||||
This generates a structural graph without semantic edges.
|
||||
|
||||
**2. Generate the graph:**
|
||||
|
||||
From your project root:
|
||||
Graphify has two execution paths and the original `--obsidian*` flags only work on one of them. Pick the form that matches how you're invoking it:
|
||||
|
||||
```bash
|
||||
# Full pipeline + Obsidian notes in the centralized vault
|
||||
graphify . --obsidian --obsidian-dir ~/vault/graphify/project-name
|
||||
**A. Inside Claude Code (skill — recommended for this guide):**
|
||||
|
||||
```
|
||||
/graphify . --obsidian --obsidian-dir ~/vault/graphify/project-name
|
||||
```
|
||||
|
||||
Generated output:
|
||||
This runs the `/graphify` slash command, which the skill at `~/.claude/skills/graphify/SKILL.md` parses. The skill calls `graphify.export.to_obsidian()` in Python directly, so `--obsidian` and `--obsidian-dir` are recognized here — they're not part of the headless shell parser.
|
||||
|
||||
**B. From the terminal / CI (headless CLI):**
|
||||
|
||||
```bash
|
||||
graphify extract . --out ./graphify-out
|
||||
```
|
||||
|
||||
The headless CLI uses subcommands (`extract`, `update`, `watch`, `tree`) and does **not** expose `--obsidian` / `--obsidian-dir` / `--wiki` / `--mode deep`. If you want Obsidian integration from the terminal, symlink the output directory into your vault after extraction:
|
||||
|
||||
```bash
|
||||
ln -s $(pwd)/graphify-out ~/vault/graphify/project-name/graphify-out
|
||||
```
|
||||
|
||||
Generated output (varies by path and flags):
|
||||
|
||||
```
|
||||
your-project/
|
||||
└── graphify-out/
|
||||
├── graph.json # queryable graph (Claude Code uses this)
|
||||
├── graph.html # interactive visualization (open in browser)
|
||||
├── GRAPH_REPORT.md # god nodes, connections, metrics
|
||||
├── wiki/ # Wikipedia-style articles (agent navigation)
|
||||
├── graph.json # queryable graph (always)
|
||||
├── graph.html # interactive viz (skill auto-generates; headless: see step 3)
|
||||
├── GRAPH_REPORT.md # god nodes, connections, metrics (always)
|
||||
├── wiki/ # Wikipedia-style articles (skill form with --wiki only)
|
||||
└── cache/ # SHA256 cache
|
||||
|
||||
~/vault/graphify/project-name/
|
||||
└── (Obsidian notes) # each function/module as a node in graph view
|
||||
~/vault/graphify/project-name/ # only when skill form was given --obsidian
|
||||
└── (Obsidian notes) # one note per function/module
|
||||
```
|
||||
|
||||
**3. Update .gitignore:**
|
||||
**3. Generate interactive visualization (headless only):**
|
||||
|
||||
The skill auto-generates `graph.html` during extraction. For the headless path, run the visualization as a separate step:
|
||||
|
||||
```bash
|
||||
graphify tree --graph ./graphify-out/graph.json --output ./graphify-out/GRAPH_TREE.html
|
||||
```
|
||||
|
||||
Open the HTML file in a browser to explore the graph interactively.
|
||||
|
||||
**4. Update .gitignore:**
|
||||
|
||||
```gitignore
|
||||
# Graphify
|
||||
@@ -356,7 +399,7 @@ graphify-out/cache/
|
||||
|
||||
Keep `graph.json` and `GRAPH_REPORT.md` versioned — they're useful for the team.
|
||||
|
||||
**4. Add to the project's CLAUDE.md:**
|
||||
**5. Add to the project's CLAUDE.md:**
|
||||
|
||||
Append to the CLAUDE.md at the repository root:
|
||||
|
||||
@@ -372,7 +415,8 @@ Append to the CLAUDE.md at the repository root:
|
||||
|
||||
### When to rebuild the graph
|
||||
- After structural changes (new modules, major refactors)
|
||||
- Command: `graphify . --update` (only processes modified files)
|
||||
- Headless: `graphify update .` (only processes modified files)
|
||||
- Skill: `/graphify . --update` (same behavior, runs through the skill — also accepts `--obsidian` to refresh the vault)
|
||||
- The graph is persistent — NO need to rebuild every session
|
||||
|
||||
### Do NOT
|
||||
@@ -380,7 +424,7 @@ Append to the CLAUDE.md at the repository root:
|
||||
- Don't re-read the entire codebase if the graph already has the information
|
||||
```
|
||||
|
||||
**5. Add to the vault's CLAUDE.md:**
|
||||
**6. Add to the vault's CLAUDE.md:**
|
||||
|
||||
```markdown
|
||||
## Graphify (Codebase Maps)
|
||||
@@ -395,7 +439,7 @@ Append to the CLAUDE.md at the repository root:
|
||||
- Filter by `-path:graphify` to hide code nodes
|
||||
```
|
||||
|
||||
**6. Git Hook (optional):**
|
||||
**7. Git Hook (optional):**
|
||||
|
||||
Automatically rebuilds the graph on every commit:
|
||||
|
||||
@@ -403,36 +447,57 @@ Automatically rebuilds the graph on every commit:
|
||||
graphify hook install
|
||||
```
|
||||
|
||||
**7. Watch Mode (optional):**
|
||||
**8. Watch Mode (optional):**
|
||||
|
||||
Auto-rebuild on file save (run in a separate terminal):
|
||||
Auto-rebuild on file save. Pick the form that matches how you invoke graphify.
|
||||
|
||||
Headless (separate terminal):
|
||||
|
||||
```bash
|
||||
graphify . --watch
|
||||
graphify watch .
|
||||
```
|
||||
|
||||
Skill (inside Claude Code):
|
||||
|
||||
```
|
||||
/graphify . --watch
|
||||
```
|
||||
|
||||
### Useful Commands
|
||||
|
||||
The table below lists the **headless CLI** subcommands you'd run in a terminal. Inside Claude Code, the same operations are available via the `/graphify` slash form documented in `~/.claude/skills/graphify/SKILL.md` — that form additionally supports `--obsidian`, `--obsidian-dir`, `--wiki`, and `--mode deep` (which the headless parser doesn't expose).
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `graphify .` | Full pipeline on current directory |
|
||||
| `graphify ./src` | Scan specific folder |
|
||||
| `graphify . --update` | Only process modified files |
|
||||
| `graphify . --mode deep` | Semantic extraction (uses LLM, costs tokens) |
|
||||
| `graphify . --watch` | Auto-rebuild on save |
|
||||
| `graphify extract .` | Full extraction on current directory |
|
||||
| `graphify extract ./src` | Scan specific folder |
|
||||
| `graphify update .` | Only process modified files |
|
||||
| `graphify watch .` | Auto-rebuild on save |
|
||||
| `graphify query "question"` | Query the graph directly |
|
||||
| `open graphify-out/graph.html` | Open interactive visualization |
|
||||
| `graphify explain "NodeName"` | Plain-language explanation of a node |
|
||||
| `graphify path "A" "B"` | Shortest path between two nodes |
|
||||
| `graphify tree --graph ./graphify-out/graph.json --output ./graphify-out/GRAPH_TREE.html` | Generate interactive visualization |
|
||||
| `open graphify-out/graph.html` | Open interactive visualization (skill-generated) or `GRAPH_TREE.html` (headless) |
|
||||
|
||||
### Adding New Projects
|
||||
|
||||
With a centralized vault, each project is just a subfolder:
|
||||
With a centralized vault, each project is just a subfolder. Same two paths as the initial setup.
|
||||
|
||||
Skill (inside Claude Code):
|
||||
|
||||
```
|
||||
/graphify ~/another-project --obsidian --obsidian-dir ~/vault/graphify/another-project
|
||||
```
|
||||
|
||||
Headless (terminal):
|
||||
|
||||
```bash
|
||||
cd ~/another-project
|
||||
graphify . --obsidian --obsidian-dir ~/vault/graphify/another-project
|
||||
graphify extract . --out ./graphify-out
|
||||
ln -s $(pwd)/graphify-out ~/vault/graphify/another-project/graphify-out
|
||||
```
|
||||
|
||||
Notes automatically appear in Obsidian's graph view alongside everything else.
|
||||
Drop the `ln -s` line if you don't need Obsidian to pick up the graph. Notes appear in Obsidian's graph view alongside everything else.
|
||||
|
||||
---
|
||||
|
||||
@@ -539,7 +604,7 @@ Check that the project's CLAUDE.md has the "Context Navigation" section and that
|
||||
Grant Full Disk Access to your terminal in System Preferences → Privacy & Security.
|
||||
|
||||
**Graphify doesn't generate wiki:**
|
||||
The wiki requires semantic edges. In AST-only mode, use `graphify query "question"` or run `--mode deep` (costs API tokens).
|
||||
The `wiki/` folder is only produced by the **skill form with `--wiki`** (`/graphify . --wiki` inside Claude Code). The headless `graphify extract` subcommand doesn't expose `--wiki`. From the terminal, use `graphify query "question"` against `graph.json` instead, or run the skill form if you need the Wikipedia-style articles.
|
||||
|
||||
**Files with parentheses in name:**
|
||||
Graphify generates notes like `myFunction().md`. Obsidian may struggle indexing files with `()` in the name. If needed, batch rename:
|
||||
@@ -548,9 +613,15 @@ cd ~/vault/graphify/project
|
||||
for f in *"("*; do mv "$f" "$(echo "$f" | sed 's/[()]//g')"; done
|
||||
```
|
||||
**Unknown Command error in graphify:**
|
||||
If an `unknown command '.'` error occurs in the `Generate the graph` step, in newer versions the `update` parameter should be placed immediately after `graphify`, resulting in:
|
||||
If `graphify .` errors with `unknown command '.'`, you're running the **headless CLI** — which requires a subcommand (`extract`, `update`, `watch`, etc.) before the path. Either use the headless form:
|
||||
```bash
|
||||
graphify update . --obsidian --obsidian-dir ~/vault/graphify/project-name
|
||||
graphify extract . --out ./graphify-out
|
||||
# or, to refresh an existing graph:
|
||||
graphify update .
|
||||
```
|
||||
Or, inside Claude Code, use the **skill form** with the leading slash — which routes through the `/graphify` skill rather than the shell parser and supports the full flag set (`--obsidian`, `--obsidian-dir`, `--wiki`, `--mode deep`, etc.):
|
||||
```
|
||||
/graphify . --obsidian --obsidian-dir ~/vault/graphify/project-name
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
+96
-31
@@ -318,36 +318,79 @@ Instale a extensão **"Export Claude Chat to Markdown"** no Chrome/Edge. Faça b
|
||||
|
||||
```bash
|
||||
pip install graphifyy
|
||||
graphify install
|
||||
graphify install --platform claude
|
||||
```
|
||||
|
||||
O `graphify install` cria o skill em `~/.claude/skills/graphify/SKILL.md`.
|
||||
O `graphify install --platform claude` cria o skill em `~/.claude/skills/graphify/SKILL.md`. Outras plataformas também são suportadas (`cursor`, `codex`, `opencode`, etc.).
|
||||
|
||||
**1.5. Configurar API key (necessário para extração semântica):**
|
||||
|
||||
O Graphify precisa de uma API key de LLM da Anthropic ou da Moonshot (Kimi) para extração semântica. Exporte uma antes de rodar:
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="sua-chave-aqui"
|
||||
# ou
|
||||
export MOONSHOT_API_KEY="sua-chave-aqui"
|
||||
```
|
||||
|
||||
Se quiser pular custos de LLM completamente, use o modo AST-only:
|
||||
|
||||
```bash
|
||||
graphify extract . --out ./graphify-out --no-cluster
|
||||
```
|
||||
|
||||
Isso gera um grafo estrutural sem edges semânticas.
|
||||
|
||||
**2. Gerar o grafo:**
|
||||
|
||||
Na raiz do seu projeto:
|
||||
O Graphify tem dois caminhos de execução e as flags `--obsidian*` originais só funcionam em um deles. Escolha o formato que corresponde a como você está invocando:
|
||||
|
||||
```bash
|
||||
# Pipeline completa + notas Obsidian no vault centralizado
|
||||
graphify . --obsidian --obsidian-dir ~/vault/graphify/nome-do-projeto
|
||||
**A. Dentro do Claude Code (skill — recomendado para este guia):**
|
||||
|
||||
```
|
||||
/graphify . --obsidian --obsidian-dir ~/vault/graphify/nome-do-projeto
|
||||
```
|
||||
|
||||
Output gerado:
|
||||
Isso roda o slash command `/graphify`, que o skill em `~/.claude/skills/graphify/SKILL.md` interpreta. O skill chama `graphify.export.to_obsidian()` em Python diretamente, então `--obsidian` e `--obsidian-dir` são reconhecidas aqui — elas não fazem parte do parser do shell headless.
|
||||
|
||||
**B. Do terminal / CI (CLI headless):**
|
||||
|
||||
```bash
|
||||
graphify extract . --out ./graphify-out
|
||||
```
|
||||
|
||||
O CLI headless usa subcomandos (`extract`, `update`, `watch`, `tree`) e **não** expõe `--obsidian` / `--obsidian-dir` / `--wiki` / `--mode deep`. Se quiser integração com Obsidian a partir do terminal, faça um symlink do diretório de output para o vault depois da extração:
|
||||
|
||||
```bash
|
||||
ln -s $(pwd)/graphify-out ~/vault/graphify/nome-do-projeto/graphify-out
|
||||
```
|
||||
|
||||
Output gerado (varia conforme o caminho e as flags):
|
||||
|
||||
```
|
||||
seu-projeto/
|
||||
└── graphify-out/
|
||||
├── graph.json # grafo consultável (o Claude Code usa este)
|
||||
├── graph.html # visualização interativa (abra no browser)
|
||||
├── GRAPH_REPORT.md # god nodes, conexões, métricas
|
||||
├── wiki/ # artigos estilo Wikipedia (navegação do agente)
|
||||
├── graph.json # grafo consultável (sempre)
|
||||
├── graph.html # viz interativa (skill auto-gera; headless: ver passo 3)
|
||||
├── GRAPH_REPORT.md # god nodes, conexões, métricas (sempre)
|
||||
├── wiki/ # artigos estilo Wikipedia (só skill com --wiki)
|
||||
└── cache/ # cache SHA256
|
||||
|
||||
~/vault/graphify/nome-do-projeto/
|
||||
└── (notas Obsidian) # cada função/módulo como um nó no graph view
|
||||
~/vault/graphify/nome-do-projeto/ # só quando o skill recebeu --obsidian
|
||||
└── (notas Obsidian) # uma nota por função/módulo
|
||||
```
|
||||
|
||||
**3. Atualizar .gitignore:**
|
||||
**3. Gerar visualização interativa (só no caminho headless):**
|
||||
|
||||
O skill auto-gera `graph.html` durante a extração. Para o caminho headless, rode a visualização como passo separado:
|
||||
|
||||
```bash
|
||||
graphify tree --graph ./graphify-out/graph.json --output ./graphify-out/GRAPH_TREE.html
|
||||
```
|
||||
|
||||
Abra o arquivo HTML no navegador para explorar o grafo interativamente.
|
||||
|
||||
**4. Atualizar .gitignore:**
|
||||
|
||||
```gitignore
|
||||
# Graphify
|
||||
@@ -356,7 +399,7 @@ graphify-out/cache/
|
||||
|
||||
Mantenha `graph.json` e `GRAPH_REPORT.md` versionados.
|
||||
|
||||
**4. Adicionar ao CLAUDE.md do projeto:**
|
||||
**5. Adicionar ao CLAUDE.md do projeto:**
|
||||
|
||||
Adicione ao final do CLAUDE.md na raiz do repositório:
|
||||
|
||||
@@ -372,7 +415,8 @@ Adicione ao final do CLAUDE.md na raiz do repositório:
|
||||
|
||||
### Quando reconstruir o grafo
|
||||
- Após mudanças estruturais (novos módulos, refactors)
|
||||
- Comando: `graphify . --update` (só processa arquivos modificados)
|
||||
- Headless: `graphify update .` (só processa arquivos modificados)
|
||||
- Skill: `/graphify . --update` (mesmo comportamento, rodando via skill — também aceita `--obsidian` para atualizar o vault)
|
||||
- O grafo é persistente — NÃO precisa reconstruir a cada sessão
|
||||
|
||||
### O que NÃO fazer
|
||||
@@ -380,7 +424,7 @@ Adicione ao final do CLAUDE.md na raiz do repositório:
|
||||
- Não releia o codebase inteiro se o grafo já tem a informação
|
||||
```
|
||||
|
||||
**5. Adicionar ao CLAUDE.md do vault:**
|
||||
**6. Adicionar ao CLAUDE.md do vault:**
|
||||
|
||||
```markdown
|
||||
## Graphify (Mapas de Codebase)
|
||||
@@ -395,7 +439,7 @@ Adicione ao final do CLAUDE.md na raiz do repositório:
|
||||
- Filtrar por `-path:graphify` para esconder nós de código
|
||||
```
|
||||
|
||||
**6. Git Hook (opcional):**
|
||||
**7. Git Hook (opcional):**
|
||||
|
||||
Reconstrói o grafo automaticamente a cada commit:
|
||||
|
||||
@@ -403,36 +447,57 @@ Reconstrói o grafo automaticamente a cada commit:
|
||||
graphify hook install
|
||||
```
|
||||
|
||||
**7. Watch Mode (opcional):**
|
||||
**8. Watch Mode (opcional):**
|
||||
|
||||
Rebuild automático ao salvar arquivos (rode em terminal separado):
|
||||
Rebuild automático ao salvar arquivos. Escolha o formato conforme como você invoca o graphify.
|
||||
|
||||
Headless (terminal separado):
|
||||
|
||||
```bash
|
||||
graphify . --watch
|
||||
graphify watch .
|
||||
```
|
||||
|
||||
Skill (dentro do Claude Code):
|
||||
|
||||
```
|
||||
/graphify . --watch
|
||||
```
|
||||
|
||||
### Comandos Úteis
|
||||
|
||||
A tabela abaixo lista os subcomandos do **CLI headless** que você rodaria no terminal. Dentro do Claude Code, as mesmas operações estão disponíveis via o slash command `/graphify` documentado em `~/.claude/skills/graphify/SKILL.md` — esse formato aceita adicionalmente `--obsidian`, `--obsidian-dir`, `--wiki` e `--mode deep` (que o parser headless não expõe).
|
||||
|
||||
| Comando | Descrição |
|
||||
|---------|-----------|
|
||||
| `graphify .` | Pipeline completa no diretório atual |
|
||||
| `graphify ./src` | Escanear pasta específica |
|
||||
| `graphify . --update` | Só processa arquivos modificados |
|
||||
| `graphify . --mode deep` | Extração semântica (usa LLM, consome tokens) |
|
||||
| `graphify . --watch` | Auto-rebuild ao salvar |
|
||||
| `graphify extract .` | Extração completa no diretório atual |
|
||||
| `graphify extract ./src` | Escanear pasta específica |
|
||||
| `graphify update .` | Só processa arquivos modificados |
|
||||
| `graphify watch .` | Auto-rebuild ao salvar |
|
||||
| `graphify query "pergunta"` | Consultar o grafo diretamente |
|
||||
| `open graphify-out/graph.html` | Abrir visualização interativa |
|
||||
| `graphify explain "NomeDoNo"` | Explicação em linguagem natural de um nó |
|
||||
| `graphify path "A" "B"` | Caminho mais curto entre dois nós |
|
||||
| `graphify tree --graph ./graphify-out/graph.json --output ./graphify-out/GRAPH_TREE.html` | Gerar visualização interativa |
|
||||
| `open graphify-out/graph.html` | Abrir visualização interativa (skill gera) ou `GRAPH_TREE.html` (headless) |
|
||||
|
||||
### Adicionando Novos Projetos
|
||||
|
||||
Com vault centralizado, cada projeto é uma subpasta:
|
||||
Com vault centralizado, cada projeto é uma subpasta. Mesmos dois caminhos do setup inicial.
|
||||
|
||||
Skill (dentro do Claude Code):
|
||||
|
||||
```
|
||||
/graphify ~/outro-projeto --obsidian --obsidian-dir ~/vault/graphify/outro-projeto
|
||||
```
|
||||
|
||||
Headless (terminal):
|
||||
|
||||
```bash
|
||||
cd ~/outro-projeto
|
||||
graphify . --obsidian --obsidian-dir ~/vault/graphify/outro-projeto
|
||||
graphify extract . --out ./graphify-out
|
||||
ln -s $(pwd)/graphify-out ~/vault/graphify/outro-projeto/graphify-out
|
||||
```
|
||||
|
||||
As notas aparecem automaticamente no graph view do Obsidian.
|
||||
Pule a linha do `ln -s` se você não precisa que o Obsidian enxergue o grafo. As notas aparecem no graph view do Obsidian junto com tudo o mais.
|
||||
|
||||
---
|
||||
|
||||
@@ -539,7 +604,7 @@ Verifique se o CLAUDE.md do projeto tem a seção "Context Navigation" e se `gra
|
||||
Dê permissão de Full Disk Access ao terminal em Preferências do Sistema → Privacidade e Segurança.
|
||||
|
||||
**Graphify não gera wiki:**
|
||||
A wiki requer edges semânticas. No modo AST-only, use `graphify query "pergunta"` ou rode `--mode deep` (consome tokens da API).
|
||||
A pasta `wiki/` só é produzida pelo **formato skill com `--wiki`** (`/graphify . --wiki` dentro do Claude Code). O subcomando headless `graphify extract` não expõe `--wiki`. Do terminal, use `graphify query "pergunta"` contra o `graph.json`, ou rode o formato skill se precisar dos artigos estilo Wikipedia.
|
||||
|
||||
**Arquivos com parênteses no nome:**
|
||||
O Graphify gera notas como `minhaFuncao().md`. O Obsidian pode ter dificuldades de indexação com `()` nos nomes. Se necessário, renomeie em batch:
|
||||
|
||||
Reference in New Issue
Block a user