Share Context Between Pi and Claude Code

The smallest truthful way to share context between Pi and Claude Code is to commit neutral repository guidance in AGENTS.md, import it from Claude Code’s CLAUDE.md, keep tool-specific procedures in native Skills, and expose current code relationships through a read-only model-independent layer. Do not copy sessions or agent summaries into a universal memory and assume the tools now understand the repository the same way.

This pattern follows the tools’ documented loading behavior. Pi prefers AGENTS.md over CLAUDE.md in each directory. Claude Code reads CLAUDE.md and documents @AGENTS.md as a compatibility import. The shared file therefore remains canonical, while Claude-specific instructions can follow the import.

The article was checked against Pi v0.82.0 and current Claude Code documentation on July 24, 2026. A shared graph or index is an external team layer, not native shared memory in either tool.

Pi stores task conversations as JSONL session trees and can compact older turns, but session history is not organization-wide shared memory. Claude Code has separate CLAUDE.md, Skills, and auto-memory surfaces; tool-specific rules must remain distinct from repository facts.

Before Sharing Repository Knowledge

To share context between Pi and Claude Code safely, classify each item as neutral guidance, tool-specific procedure, task state, or revision-bound repository evidence.

Separate information by authority and lifecycle before choosing files.

Share stable, tool-neutral guidance:

• repository purpose and major boundaries;
• approved build, test, lint, and formatting commands;
• generated-code and migration rules;
• security and data-handling constraints;
• ownership and escalation paths;
• links to authoritative architecture records.

Do not put these items in a universal file:

• tool permission syntax;
• provider-specific commands or plugins;
• one session’s private reasoning;
• temporary branch state;
• unrestricted credentials;
• volatile lists of callers, dependencies, and tests.

The last category is especially important. A static Markdown file can describe the intention behind a boundary. It should not pretend to maintain a current call graph.

Create an inventory of existing AGENTS.md, CLAUDE.md, rules, Skills, prompt templates, and repository indexes. Resolve contradictions before adding imports. Otherwise sharing simply distributes existing drift.

Define a Model-Independent Context Layer

Start the model-independent code context layer with one neutral instruction file and one revision-aware query contract.

Commit a root AGENTS.md containing only neutral guidance. Pi’s resource loader walks from ancestor directories toward the current directory and selects the first recognized context candidate per directory, preferring AGENTS.md. Nested directories can add narrower AGENTS.md files as needed.

Create a root CLAUDE.md like this:

@AGENTS.md

# Claude Code-specific guidance

- Use the project permission rules for read-only analysis.
- Invoke the repository-analysis Skill for cross-module impact work.

Claude Code resolves the import; Pi selects AGENTS.md first and does not need to interpret Claude’s import syntax. Pi’s CLI @file argument only adds a file to one user message. It is not evidence that Pi supports @import inside context files.

For dynamic model-independent code context, define a tool-neutral query schema:

repo + commit + question
→ modules + relationships + tests + sources + unknowns + index age

Both agents should receive the same relationship semantics and provenance. Claude Code can use an MCP or CLI adapter. Pi needs a CLI or extension/package adapter because built-in MCP is not documented.

Search comparisons such as Pi coding agent vs Claude Code should not change this contract. The shared layer is useful precisely because tool choice can change while the repository evidence format remains stable.

Separate Tool Preferences From System Facts

The practical Pi coding agent vs Claude Code distinction belongs in native tool behavior and permissions, not in the shared repository-fact contract.

Put tool behavior in tool-native locations.

For Pi:

• use Pi context for harness-specific defaults;
• use Skills for reusable procedures;
• use Prompt Templates for lightweight slash-command prompts;
• use extensions/packages for new tools and adapters.

For Claude Code:

• keep stable persistent instructions in CLAUDE.md and rules;
• use Skills for on-demand procedures;
• use MCP/plugins for external tools;
• enforce filesystem and command behavior with permission settings, not prose alone.

If one Agent Skill genuinely works in both harnesses, make one directory canonical and add it to Pi’s skills configuration. Test the Skill in both tools. Claude’s allowed-tools is a pre-approval mechanism; Pi labels the field experimental and does not have the same permission-popup layer. Shared frontmatter does not imply shared enforcement.

System facts belong elsewhere. Current definitions, imports, calls, registrations, schemas, event flows, generated sources, and test mappings must come from current source or a revision-bound index. Store file and symbol citations beside each material relationship.

Reuse Graph Queries Across Both Agents

Design a small set of task-shaped queries:

• locate the authoritative definition and entry point;
• trace direct, indirect, and unresolved callers;
• map change impact across modules and contracts;
• find relevant tests and coverage gaps;
• retrieve architecture decisions connected to a component.

Return bounded results with indexed_commit, source locations, extraction method, confidence or edge type, and failed coverage. The adapter should reject a task when its checkout does not match the indexed commit.

A shared query does not require identical runtime integration. Claude Code may call repo_graph.impact through MCP. Pi may run repo-graph impact --json. Normalize both responses into the same evidence object before the Skill interprets them.

Keep the service read-only for task agents. Index updates run separately and produce reviewable artifacts. Require both tools to verify high-impact edges in their checkouts and record mismatches. This prevents a stale graph from becoming a cross-tool source of synchronized error.

Define a portable handoff file for tasks that genuinely move from one harness to the other. Keep it small and factual:

task: AUTH-214
repository: platform
base_commit: 8f31c2a
inspected_paths: []
verified_relationships: []
tests_run: []
decisions: []
unknowns: []

The handoff should not contain secrets, unrestricted tool output, or a claim that hidden reasoning was transferred. The receiving agent rechecks the base commit, opens cited paths, and confirms material relationships. If the branch moved, it refreshes the evidence packet before continuing.

Version shared files and adapters together in a small compatibility matrix. Record which Pi release, Claude Code release, Skill hash, and query schema were tested. A Markdown instruction may remain readable after a tool update while its permission frontmatter or adapter command changes meaning. Run fixture tasks after upgrades: one normal query, one denied repository, one revision mismatch, and one deliberately unresolved edge. Treat a silent fallback to broad shell search as a failed integration, not a successful shared-context run.

Keep one human-readable migration note beside the matrix. It should explain removed commands, changed permission assumptions, renamed Skills, and the rollback path. This prevents a tool upgrade from becoming an invisible context fork across developer machines.

Review it together.

Roll the pattern out in read-only mode first. Choose one repository and two analysis tasks, record which files each harness loads, and compare the evidence objects returned by both adapters. Fix differences in path normalization, symbol identity, permission denial, and revision handling before allowing either tool to edit.

After the pilot, assign owners to the shared file, each native Skill, and the repository index. Define a response time for a stale or incorrect relationship. Without ownership, the shared layer becomes another abandoned document that both agents load confidently.

Keep an escape hatch. If the adapter fails or the index is behind, the agent should state the limitation and either stop or use a documented bounded source-search fallback. It should never silently switch to an unrestricted repository scan and report the result as graph-backed context.

Conflict, Permission, and Drift Risks

The cross-tool system can fail in four places.

Instruction conflict: a nested file or duplicate Skill overrides or competes with shared guidance. Record which files and Skill hashes each run loaded.

Fact conflict: an agent summary or graph edge disagrees with current source. Preserve both claims, verify at the task commit, and update the derived layer after review.

Permission mismatch: one harness pre-approves a tool that the other treats differently. Apply OS credentials, repository access, and tool-native permission controls independently.

Revision drift: the graph, session, and checkout refer to different commits. Make revision mismatch a hard stop for material impact analysis.

Resolve conflicts by provenance and authority, not length or confidence. Current source supports implementation facts. Approved policy and architecture records explain intended constraints. Humans decide security, ownership, destructive operations, and material unresolved architecture questions.

FAQ

What should stay tool-specific?

Keep permissions, plugin or extension setup, provider configuration, native commands, and harness-specific procedures in Pi or Claude Code locations. Share only neutral repository guidance and a common evidence schema.

How should conflicting summaries be handled?

Record each summary’s task, commit, cited paths, and creation time. Verify the disputed claim in current source. Update or retire the derived summary; do not choose whichever agent sounds more certain.

Who approves shared context updates?

Code owners approve structural or architecture changes, security owners approve sensitive rules, and Skill maintainers approve workflow changes. Automated index refreshes can update observed edges, but schema and manual-fact changes need review.

install pi-coding agent

Use the installation method in the current first-party earendil-works/pi documentation and pin the version for reproducible team setups. Installation alone does not enable Claude-style MCP or import semantics; configure the shared adapters explicitly.

Conclusion

Share a small committed instruction core, not an undifferentiated memory dump. Let Pi read AGENTS.md; let Claude Code import it from CLAUDE.md; keep native procedures and permissions separate; and give both tools one revision-bound evidence contract for current code relationships. This setup is simple enough to audit and honest about what the tools do not share.