# First Run & Assistant Setup

> The smallest useful path from installing graphifyy to running graphify, registering assistant skills, and understanding why project-scoped installs stay portable across coding agents.

- Repository: safishamsi/graphify
- GitHub: https://github.com/safishamsi/graphify
- Human wiki: https://grok-wiki.com/public/wiki/safishamsi-graphify-af19ef9fd72d
- Complete Markdown: https://grok-wiki.com/public/wiki/safishamsi-graphify-af19ef9fd72d/llms-full.txt

## Source Files

- `graphify/__main__.py`
- `graphify/skill.md`
- `graphify/skill-codex.md`
- `graphify/hooks.py`
- `tests/test_install.py`
- `tests/test_hooks.py`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [README.md](README.md)
- [pyproject.toml](pyproject.toml)
- [graphify/__main__.py](graphify/__main__.py)
- [graphify/skill.md](graphify/skill.md)
- [graphify/skill-codex.md](graphify/skill-codex.md)
- [graphify/hooks.py](graphify/hooks.py)
- [graphify/llm.py](graphify/llm.py)
- [tests/test_install.py](tests/test_install.py)
- [tests/test_hooks.py](tests/test_hooks.py)
</details>

# First Run & Assistant Setup

This page shows the smallest useful path from installing the `graphifyy` Python package to using the `graphify` CLI and registering the assistant skill that powers `/graphify`.

The simple mental model is: install the tool once, register a small instruction file for your assistant, then let the assistant build or query `graphify-out/`. Project-scoped installs matter because they put those instructions inside the repository, so the setup can travel with the code instead of depending on one developer's home directory.

## The Shortest First Run

Use the package name `graphifyy`, then run the CLI named `graphify`:

```bash
uv tool install graphifyy
graphify install
```

Then open the supported coding assistant and run:

```text
/graphify .
```

The README calls out the double-y package name, recommends `uv tool install graphifyy`, and explains that the command exposed to users is still `graphify`. It also documents the two-step flow: install the package, then run `graphify install` to register the assistant skill.  
Sources: [README.md:80-99](), [pyproject.toml:5-12](), [pyproject.toml:68-70]()

If `graphify` is not on `PATH`, the README recommends `uv tool install graphifyy` or `pipx install graphifyy`; plain `pip` may require adding the user script directory to `PATH` or running `python -m graphify`.  
Sources: [README.md:84-90](), [README.md:115-117]()

## What `graphify install` Actually Does

`graphify install` copies a packaged skill file into the selected assistant's skill directory. By default it targets Claude Code on Linux/macOS and the Windows Claude skill on Windows. The platform map includes Codex, OpenCode, Aider, OpenClaw, Factory Droid, Trae, Hermes, Pi, Antigravity, Kimi, Gemini, Cursor, and related variants.  
Sources: [graphify/__main__.py:206-287](), [graphify/__main__.py:1496-1541]()

A few concrete destinations:

| Platform | Skill/config destination |
|---|---|
| Claude Code | `.claude/skills/graphify/SKILL.md` |
| Codex | `.agents/skills/graphify/SKILL.md` |
| OpenCode | `.config/opencode/skills/graphify/SKILL.md` |
| OpenClaw | `.openclaw/skills/graphify/SKILL.md` |
| Factory Droid | `.factory/skills/graphify/SKILL.md` |
| Trae | `.trae/skills/graphify/SKILL.md` |

The install tests verify these destinations and also verify that all packaged skill markdown files exist in the package.  
Sources: [tests/test_install.py:9-18](), [tests/test_install.py:32-45](), [tests/test_install.py:254-260]()

## User-Scoped vs Project-Scoped Setup

By default, installs go into the current user's assistant configuration. That is good for a personal machine, but it does not travel with the repository.

For a portable repository setup, add `--project`:

```bash
graphify install --project
graphify install --project --platform codex
```

Project-scoped installs write into the current directory, for example `.claude/skills/graphify/SKILL.md` or `.agents/skills/graphify/SKILL.md`, and print a `git add` hint so the files can be committed.  
Sources: [README.md:101-113](), [graphify/__main__.py:160-173]()

```text
User-scoped install
  ~/.claude/skills/graphify/SKILL.md
  ~/.agents/skills/graphify/SKILL.md

Project-scoped install
  ./AGENTS.md
  ./.agents/skills/graphify/SKILL.md
  ./.codex/hooks.json
  ./.claude/skills/graphify/SKILL.md
  ./.claude/settings.json
```

The key safety property is scope separation. Tests create a fake home directory and a fake project, install with `--project`, and assert that the project receives the skill files while the home directory is not modified. Separate uninstall tests assert that project uninstall removes only project files and leaves user-scoped skill files alone.  
Sources: [tests/test_install.py:57-87](), [tests/test_install.py:89-141](), [graphify/__main__.py:1059-1115]()

## Assistant Instructions: Query First, Then Read Files

The installed instructions tell assistants to use the graph before broad source browsing. For Claude-style installs, the generated section says to run `graphify query "<question>"` when `graphify-out/graph.json` exists, use `graphify path "<A>" "<B>"` for relationship questions, and use `graphify explain "<concept>"` for focused concepts. It also tells the assistant to prefer `graphify-out/wiki/index.md` when present and to update the graph after code edits.  
Sources: [graphify/__main__.py:395-405]()

For Codex and other AGENTS.md-based platforms, the generated section adds one practical caveat: dirty `graphify-out/` files are expected after hooks or incremental updates and are not by themselves a reason to skip Graphify.  
Sources: [graphify/__main__.py:409-424](), [tests/test_install.py:217-222]()

The skill files carry the same behavior. The generic skill says that if `graphify-out/graph.json` exists and the user asks a natural-language codebase question, the assistant should run `graphify query` immediately instead of re-detecting or re-extracting. The Codex skill says the same graph-first behavior should still apply when `graphify-out/` is dirty.  
Sources: [graphify/skill.md:37-58](), [graphify/skill-codex.md:52-60]()

## Hooks: Helpful Nudges, Not the Whole System

Some assistants support hooks that can run before tool use. Graphify uses those hooks as nudges toward the graph, but the durable setup is still the skill or instruction file.

Claude project setup writes `CLAUDE.md` and registers a `PreToolUse` hook in `.claude/settings.json`. Codex project setup writes `AGENTS.md` and registers a `PreToolUse` hook in `.codex/hooks.json`; the hook calls `graphify hook-check`, which intentionally exits silently because Codex Desktop rejects payload-bearing `additionalContext` from that hook path.  
Sources: [graphify/__main__.py:1159-1205](), [graphify/__main__.py:979-1008](), [graphify/__main__.py:2223-2279](), [tests/test_hooks.py:164-180]()

For Git repositories, `graphify hook install` installs both `post-commit` and `post-checkout` hooks. The post-commit hook rebuilds the code graph in the background after commits, and the post-checkout hook rebuilds after branch switches if `graphify-out/` already exists. Both use local AST/code rebuild paths and write logs under `~/.cache/graphify-rebuild.log`.  
Sources: [graphify/hooks.py:46-101](), [graphify/hooks.py:104-158](), [graphify/hooks.py:262-304]()

The hook tests verify that install creates executable hooks, is idempotent, preserves existing hook content, creates `post-checkout`, removes hooks on uninstall, and reports both hook statuses.  
Sources: [tests/test_hooks.py:15-52](), [tests/test_hooks.py:88-120]()

## Running Graphify After Setup

Once the assistant is registered, `/graphify .` is the normal first run from inside the assistant. The generic skill handles the workflow: ensure the package is importable, detect files, write interpreter/root metadata in `graphify-out/`, and continue into extraction. It also records the interpreter in `graphify-out/.graphify_python` and the scan root in `graphify-out/.graphify_root`, which helps later commands reuse the right environment and path.  
Sources: [graphify/skill.md:103-143](), [graphify/skill.md:169-181]()

For direct CLI usage, `graphify --help` exposes the same operational surface: `query`, `path`, `explain`, `watch`, `update`, `extract`, `hook install`, and per-platform install commands. The `update` command is explicitly code-only and prints that document, paper, and image changes require `/graphify --update` in the assistant.  
Sources: [graphify/__main__.py:1365-1481](), [graphify/__main__.py:2223-2272]()

## Provider-Neutral and BYOK-Friendly Behavior

Graphify is not tied to one model provider. The README says code is extracted locally with tree-sitter and no API calls, while docs, PDFs, and images use the assistant's model API or a configured headless backend.  
Sources: [README.md:208-221](), [README.md:357-362]()

For headless `graphify extract`, the backend layer supports multiple provider styles: Anthropic Claude, Kimi, local Ollama, Gemini, OpenAI, DeepSeek, AWS Bedrock, and a `claude-cli` route that uses a local Claude Code CLI session. API keys are read from backend-specific environment variables, while Bedrock uses the AWS credential chain and Ollama can use a local base URL.  
Sources: [graphify/llm.py:47-118](), [graphify/llm.py:214-245](), [graphify/llm.py:535-568](), [README.md:332-361]()

This keeps the assistant setup BYOC/BYOK friendly: the skill files are ordinary repository or user files, and the extraction backend is selected by command flags, environment variables, local tools, or the active IDE assistant session rather than by a hard dependency on one hosted service.

## Practical Recommendation

For a team repository, use a project-scoped install for each assistant family the team actually uses:

```bash
graphify install --project --platform codex
graphify install --project --platform claude
graphify hook install
```

Commit only the project-scoped assistant files you want the team to share. This makes the graph-first workflow portable across coding agents while keeping each developer's personal keys, local models, and assistant subscriptions outside the repository. Project-scoped install and uninstall behavior is covered by tests that confirm user-level skill files are not touched.  
Sources: [README.md:101-113](), [graphify/__main__.py:1059-1115](), [tests/test_install.py:89-141]()