profile-project

A self-contained Claude Code plugin that runs a fixed, agent-driven DAG to profile a project — source code, in-repo docs, transcripts, notes, and external references — and emit three durable deliverables:

1. Agent-facing context pages (profile/context/) — dense, multi-page markdown for fast machine consumption.
2. A human/developer guide (profile/guide/) — readable narrative documentation for onboarding.
3. A local queryable vectorstore over both, answered via pp_query.

It ships as one Python FastMCP server (profile_project) plus a skill suite and slash commands. It runs per-session over stdio, needs no Docker and no mandatory Ollama, and never writes a single local artifact to a target project until that project is explicitly initialized via /profile-project:init.

Installation

profile-project is launched by Claude Code over stdio. The host runs the server with:

uv run --directory ${CLAUDE_PLUGIN_ROOT} python -m profile_project

uv syncs the environment from the root pyproject.toml, then runs the package as a module. You need only uv and Python ≥ 3.11 on the machine.

Dependency extras

The base install is light. Backends are optional extras (a missing extra for a selected backend is a warn + disable, never a crash):

Extra	Pulls in	Required for
(base)	mcp, pydantic>=2, pydantic-settings>=2, tiktoken, structlog, httpx	server, config, DAG, chunking, ollama (httpx only)
[chroma]	chromadb	ChromaDB local store
[pinecone]	pinecone>=9.1.0	Pinecone remote store
[openai]	openai	OpenAI embeddings
[local-embeddings]	sentence-transformers	sentence-transformers (the default embedder)
[ollama]	(httpx only — already base)	Ollama embeddings
[all]	union of the above	everything

Recommended default backend. The recommended path is sentence-transformers (local, offline after first model pull, dim 384) for embeddings + chromadb (local on-disk) for storage — no Docker, no external service, no API key. For a manual/dev checkout, install it with [local-embeddings] and [chroma] (or [all]):

uv pip install -e ".[local-embeddings,chroma]"

Enabling the vectorstore on a plugin install (opt-in)

The server always starts on a plain install, but the vectorstore is off by default: the stdio launch command (uv run … python -m profile_project) installs only the base dependencies, so the embedding + store libraries are absent and the conflict matrix warns + disables the vectorstore (the DAG still runs and produces both guides). This keeps cold start fast — sentence-transformers pulls in torch (~2 GB), which is too heavy to download on every launch.

To turn the vectorstore on, add the extras to the launch command in the installed plugin's .mcp.json (${CLAUDE_PLUGIN_ROOT}/.mcp.json):

{
  "mcpServers": {
    "profile-project": {
      "command": "uv",
      "args": ["run", "--extra", "local-embeddings", "--extra", "chroma",
               "--directory", "${CLAUDE_PLUGIN_ROOT}", "python", "-m", "profile_project"]
    }
  }
}

The first launch after adding the extras resolves and downloads them (slow, one time); later launches reuse the synced environment. Swap in --extra pinecone / --extra openai (or --extra all) for the corresponding backends. Every vectorstore backend needs at least one extra; only ollama embeddings run on the base install (httpx is a base dependency) — but a store backend (chroma or pinecone) is still required.

Initialization

The plugin must be explicitly initialized per project before it writes any local artifact — this gate is enforced in the MCP server, not just the skill.

/profile-project:init

init runs read-only diagnostics (pp_config_validate, pp_vectorstore_check), collects/confirms config, validates that required secrets exist in your environment, then calls the server tool pp_init_project, which transactionally writes .profile_project_config.json, the gitignored .profile_project/ tree, the .initialized stamp, and the .gitignore entry. Until init succeeds, every mutating tool refuses with a structured not_initialized error and writes nothing.

Re-run /profile-project:init any time to reconfigure (idempotent); use /profile-project:init --reinit to overwrite/reset existing run artifacts.

Usage

Command	What it does
/profile-project:init	Initialize the project (the only path that creates initial artifacts)
/profile-project:profile	Run the full profiling DAG
/profile-project:status	Show run/phase status and what's next
/profile-project:query	Ask a semantic question over the profile
/profile-project:navigate	Browse generated pages and per-phase artifacts
/profile-project:refresh	Incrementally refresh an existing profile

A typical first run: /profile-project:init → /profile-project:profile → /profile-project:query "how is config resolved?". The generated profile/context/ and profile/guide/ directories are committable project artifacts.

Configuration

Configuration is layered. Project JSON overrides env (the inverse of agent-knowledgebase): .profile_project_config.json at the project root takes precedence over PROFILE_PROJECT_* environment variables, which act as defaults.

Precedence (highest to lowest): init kwargs → project JSON → env → .env → file secrets → field defaults.

Secrets are environment-only. PROFILE_PROJECT_OPENAI_API_KEY and PROFILE_PROJECT_PINECONE_API_KEY are modeled as SecretStr, read only from the environment, and are never written to .profile_project_config.json (the JSON source hard-rejects forbidden keys), never stamped into chunk metadata, and never logged (masked). .env.example documents the env vars and contains no real values.

Common env vars (full table in .env.example):

Env var	Maps to	Default
PROFILE_PROJECT_DEFAULT_EMBEDDINGS_METHOD	embeddings.method	(unset → init prompts)
PROFILE_PROJECT_VECTORSTORE__BACKEND	vectorstore.backend	(unset → init prompts)
PROFILE_PROJECT_CHROMADB__PATH	vectorstore.chromadb.path	.profile_project/chroma
PROFILE_PROJECT_OPENAI_API_KEY	openai_api_key (secret)	(none)
PROFILE_PROJECT_PINECONE_API_KEY	pinecone_api_key (secret)	(none)

Embeddings. The default embedder's canonical geometry id is sentence-transformers/all-MiniLM-L6-v2@hf-fp32 (stamped per chunk so a query-time rebuild rejects a mismatched embedder rather than returning meaningless scores). OpenAI and Ollama are alternatives selected via config.

Pinecone uses an EXISTING index only. The plugin never creates a Pinecone index. You supply an existing index ref + embeddings_model; at connect time the store validates index.dimension == effective_embedding_dim and refuses on mismatch. A missing index ref, missing key, or dimension mismatch warns + disables the vectorstore (the DAG still runs and produces the guides).

Troubleshooting

• "not_initialized" on a tool call. Run /profile-project:init first. The gate is server-enforced; no mutating tool writes before initialization.
• Vectorstore silently disabled. Run pp_config_validate and pp_vectorstore_check; a missing extra ([chroma]/[pinecone]/[openai]/[local-embeddings]), missing API key, missing Pinecone index ref, unreachable Ollama host, or dimension mismatch all warn
  • disable rather than crash. The warning names the exact cause. On a plugin install the most common cause is that the launch command installs only base deps — see Enabling the vectorstore on a plugin install above to add the --extra flags.
• pp_query returns index_disabled / index_empty. The vectorstore is off, or no vectors have been built yet — run /profile-project:profile (which runs build_vectorstore) or check pp_index_status.
• "project_root_moved". The project was initialized for a different absolute root. Run /profile-project:init --reinit.
• Garbled JSON-RPC / protocol errors. Nothing may be written to stdout under stdio transport — all logs go to stderr only. If you patched the server, ensure no print() reaches stdout.
• First profiling run is slow. sentence-transformers downloads all-MiniLM-L6-v2 once; subsequent runs are offline.

Security & hygiene

• Secrets are env-only (SecretStr): never in .profile_project_config.json, never in chunk metadata, never logged (masked).
• .profile_project/ is gitignored (local store, run-state, artifacts, cache, .initialized). The profile/ guides are intentionally committable.
• No user-specific absolute paths are written to tracked config; profile.root_dir is resolved at runtime, never persisted.
• stdio hygiene: logs go to stderr only; stdout stays clean for JSON-RPC framing.
• No remote provisioning: Pinecone indexes are never auto-created, so the plugin cannot silently incur cost.