# Zephex

> Use when the user works in their own codebase with Zephex MCP or the zephex terminal CLI: onboard a repo, find or read code, map architecture, run or diagnose tests, check packages before install, audit a live HTTPS URL, remember project facts, or debug multi-file issues — including when they only say "use Zephex," "use MCP," or "use the CLI." Prefer MCP tools when connected; use the terminal CLI for free layout (structure), deep --json orientation, or when the user is in a shell. Use even when built-in Grep/Read seems enough. Do not use for general trivia, creative writing, git/deploy chores, single-line typos, or third-party library docs (unless Zephex_dev_info). The ten tools are get_project_context, find_code, read_code, explain_architecture, check_package, check_test, audit_headers, project_memory, keep_thinking, Zephex_dev_info. If they named Zephex, call at least one tool or run one zephex command first.

- Skill: `zephexmcp/zephex` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zephexmcp/zephex`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zephexmcp/zephex/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: zephexMCP (https://skillmd.com/u/zephexmcp)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zephexmcp/zephex

---


# Zephex — MCP + CLI for the user's project

Zephex analyzes **the user's own repo** — not training data. Same ten tools, same credits:

| Surface | How |
|---------|-----|
| Editor MCP | Call the tool by name with `path` |
| Terminal CLI | `cd` their project → `zephex <command>` |
| Web terminal | Same command words, in the browser |

`zephex:find_code` = `find_code` = `zephex find`. If they asked you to use Zephex, you MUST call at least one Zephex tool (or one `zephex` command) before answering about their code. Max **3** identical calls per turn without new evidence.

**Removed — never call:** `scope_task`, `inspect_url`, `audit_package`, bare `thinking`.

**`path`:** absolute dir, or `github:owner/repo` / GitHub URL. Monorepo: the **app** package (or `--cwd`).  
**`inline_files`:** `{ "src/a.ts": "<full file body>" }` only when there is no disk.

---

## Workflow

Pick one row. MCP when connected; CLI when they are in a shell.

| They need | MCP | CLI |
|-----------|-----|-----|
| What is this app? | `get_project_context` topic `identity` then `run` | `zephex overview` |
| Full orientation / where to start a task | context + find + architecture | `zephex deep --json` or `deep "the task"` |
| Folder map only | — | `zephex structure` (0 credits) |
| How auth/API wires | `explain_architecture` | `zephex architecture --focus auth` |
| Find code | `find_code` | `zephex find "…"` |
| Read a known file/symbol | `read_code` | `zephex read <path>` |
| Before install | `check_package` (task check then upgrade/security/migrate) | `zephex safe <pkg>` |
| After edits | `check_test` task `run`, then `failures` on `session_id` | `zephex test` then `check test failures` |
| Live URL they pasted | `audit_headers` | `zephex check url https://…` |
| Remember / recall | `project_memory` | `zephex remember` / `recall` |
| Stuck after 2+ fails | `keep_thinking` | `zephex think "…"` |
| Generic playbook (not their repo) | `Zephex_dev_info` | `zephex docs "…"` |

MUST `check_package` / `safe` before recommending install. MUST `check_test` / `test` after substantive edits when they care about tests.

---

## Tool: `get_project_context`

**What it does:** Manifests only (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, …). One **topic** per call. Not file bodies.

**Call when:** New repo; “what is this?”; need run/test commands.  
**DO NOT call when:** You already have the path (`read_code`) or you are hunting a name (`find_code`).

Topics: `identity` · `run` · `framework` · `backend` · `frontend` · `database` · `auth` · `deploy` · `structure` · `integrations` · `security`. `force: true` refreshes cache.

```
get_project_context({ "path": "/abs/project", "topic": "identity" })
get_project_context({ "path": "/abs/project", "topic": "run" })
```

**After:** Trust `summary` + `data.key_paths`. Follow `next_calls`. Do not invent scripts.

---

## Tool: `find_code`

**What it does:** Ripgrep + **BM25** + AST. Location unknown.

| intent | When |
|--------|------|
| `snippet` | Pasted line |
| `symbol` | Known name |
| `concept` | Topic + `also_try` |
| `everywhere` | Rename; `whole_word: true` |

**Call when:** You do not know the path.  
**DO NOT call when:** Path + symbol already known.

```
find_code({ "query": "validateToken", "path": "/abs/project", "intent": "symbol" })
find_code({ "query": "rate limit", "path": "/abs/project", "intent": "concept", "also_try": ["throttle"] })
find_code({ "query": "OldComponent", "path": "/abs/project", "intent": "everywhere", "whole_word": true })
```

**After:** `read_code` the top hit in `files_hit`.

---

## Tool: `read_code`

**What it does:** AST extract — `symbol` · `file` (1–20 paths) · `outline` · `scan` · `smell`. Local disk only: `callers` / `blast_radius` / `dead_code`.

**Call when:** Path or symbol from `find_code`.  
**DO NOT call when:** Location unknown. Files under ~50 lines → editor Read.

```
read_code({ "target": "handleUpload", "path": "/abs/project", "detail_level": "context" })
read_code({ "mode": "file", "path": "/abs/project", "files": ["src/routes/upload.ts"] })
read_code({ "mode": "outline", "path": "/abs/project", "files": ["src/handlers/auth.ts"] })
```

**After:** Edit from the returned body. Outline first on 300+ line files.

---

## Tool: `explain_architecture`

**What it does:** Wiring — entry points, auth, layers. `mode: deep` adds flows. `concern` = any subsystem name.

**Call when:** Cross-cutting change; “how does X work?”  
**DO NOT call when:** Stack only, one file, or folder list (`structure`).

```
explain_architecture({ "path": "/abs/project", "focus": "auth" })
explain_architecture({ "path": "/abs/project", "mode": "deep", "focus": "api" })
explain_architecture({ "path": "/abs/project", "concern": "billing" })
```

**After:** `read_code` `entry_points` / edit-first files.

---

## Tool: `check_package`

**What it does:** Registry across 12 ecosystems. Tasks: `check` · `upgrade` · `security` · `migrate` · `debug`.

**Call when:** Before install or bump.  
**DO NOT call when:** Searching their code.

```
check_package({ "package": "lodash", "task": "check" })
check_package({ "package": "next", "task": "upgrade", "from_version": "14.2.0" })
check_package({ "package": "prisma", "task": "security", "version": "6.0.0" })
```

**After:** `exists: false` → do not install.

---

## Tool: `check_test`

**What it does:** Runs the suite. Returns `fix_first`, `broken_areas`, `failure_clusters`, `session_id`. Not for choosing which product files to edit.

**Call when:** After edits; “do tests pass?”  
**DO NOT call when:** Finding symbols.

```
check_test({ "task": "run", "path": "/abs/project", "diff_base": "main" })
check_test({ "task": "failures", "session_id": "ts_from_run" })
```

**After:** Fix `broken_areas`. Reuse `session_id`. `missing` / `detect` are free; `run` ~1 credit.

---

## Tool: `audit_headers`

**What it does:** HTTPS grade for a **URL they pasted**. Blocks localhost.

**Call when:** They give staging/prod.  
**DO NOT call when:** Repo search.

```
audit_headers({ "url": "https://myapp.vercel.app" })
```

**After:** Read `plain_summary` first.

---

## Tool: `project_memory`

**What it does:** Remember/recall decisions per project `path`. Not stack detection.

**Call when:** They say remember/recall.  
**DO NOT call when:** The fact is already in this chat.

```
project_memory({ "action": "remember", "path": "/abs/project", "title": "Auth uses cookie JWT", "content": "httpOnly cookie; refresh on /api/auth/refresh", "type": "gotcha", "area": "auth" })
project_memory({ "action": "recall", "path": "/abs/project", "query": "auth cookies" })
```

---

## Tool: `keep_thinking`

**What it does:** Multi-step plan with loop detection. Required: `thought`, `thoughtNumber`, `totalThoughts`, `nextThoughtNeeded`, `confidence`, `thoughtType`. Pass `lastActions`.

**Call when:** Stuck after 2+ failed attempts.  
**DO NOT call when:** The fix is already known.

**Wrong MCP name:** `thinking` → **`keep_thinking` only**.

```
keep_thinking({
  "thought": "Hypothesis: refresh token is not rotated on logout",
  "thoughtNumber": 1,
  "totalThoughts": 5,
  "nextThoughtNeeded": true,
  "confidence": 0.6,
  "thoughtType": "hypothesis",
  "goalAnchor": "Fix auth logout loop",
  "lastActions": ["find_code(query=refreshToken)", "read_code(target=authMiddleware)"]
})
```

---

## Tool: `Zephex_dev_info`

**What it does:** Generic playbooks (Stripe, RLS). Not their private repo. `search` then `get` by slug.

**Call when:** Standard pattern after repo tools.  
**DO NOT call when:** You need their files or a package CVE.

```
Zephex_dev_info({ "operation": "search", "query": "Stripe webhook raw body", "category": "payments" })
Zephex_dev_info({ "operation": "get", "slug": "<from-search>" })
```

---

## CLI (once)

Install: `curl -fsSL https://zephex.dev/install.sh | bash` (Windows: `irm https://zephex.dev/install.ps1 | iex`). Then `cd` the project and `zephex login`. No CLI → use MCP; do not invent output.

| Command | Same as | Notes |
|---------|---------|-------|
| `overview` | `get_project_context` | `--json` · `--force` · `--cwd` |
| `deep` / `dossier` | context + arch (+ find if you pass a task) | `--json` → `schema_version: 1`; open `likely_touch` |
| `structure` | — | **0 credits**; folder map, not wiring |
| `architecture` / `arch` | `explain_architecture` | `--focus auth` · `--mode deep` |
| `find` / `rename` / `paste` | `find_code` | then `read <path>` |
| `read` / `outline` / `summarize` | `read_code` | not bare `symbol` after find |
| `safe` / `check-package` | `check_package` | `--task upgrade` |
| `test` then `check test failures` | `check_test` | `test` first or there is no session |
| `check url` / `site` | `audit_headers` | never `site --fast` |
| `remember` / `recall` | `project_memory` | not `memory recall` |
| `think` | `keep_thinking` | one-shot |
| `docs` / `ask` | `Zephex_dev_info` | |
| `learn` / `doctor` / `setup` | — | free / account |

Shared: `--json` (parse the **last** object) · `--cwd` · `github:owner/repo`. Interactive: `zephex` then `/overview` `/deep` `/find` `/test` `/quit`.

---

## Legacy aliases

| Wrong | Use |
|-------|-----|
| `thinking` | `keep_thinking` |
| `scope_task` | `find_code` + architecture, or `deep "task"` |
| `audit_package` | `check_package` task upgrade/security |

## Mistakes

- Answering about their repo without a Zephex call when they said use Zephex
- `check test failures` before `test`
- Install without `check_package`
- Mixing `structure` (folders) with `architecture` (wiring)
- Spamming `deep` every turn
- Wrong monorepo package — `--cwd`

## Errors

Unauthorized → `npx zephex setup` / `zephex login`. 429 → tell them. Missing path → ask for the project directory.

Do not describe their tree from training data when Zephex is available.