Pi Claude Code Context Engineering

Pi Claude Code context engineering works best when you separate four things: always-relevant instructions, on-demand procedures, conversation state, and current repository facts. Pi and Claude Code implement the first three with different files and runtime features. Neither tool should be the sole source of truth for dynamic module, dependency, call-chain, or test relationships.

This is a layer-design problem, not a contest over who can load more text. Good context is the minimum material that helps an agent act correctly at the current repository revision. It has an owner, scope, source, refresh trigger, and verification rule.

The product facts below were checked on July 24, 2026 against Pi v0.82.0 and current Claude Code documentation. Pi refers to the earendil-works/pi terminal coding harness.

Quick Verdict

Pi Claude Code context engineering works best when stable instructions, on-demand procedures, session state, and revision-bound repository facts remain distinct.

Use tool-native context for tool-native behavior:

• Pi context files, Skills, Prompt Templates, extensions, packages, and sessions should control how Pi operates.
• Claude Code CLAUDE.md, rules, Skills, auto memory, plugins/MCP, subagents, and sessions should control how Claude Code operates.

Use committed neutral instructions for conventions both tools must follow. Use source code and a model-independent context layer for repository facts that both tools need to query. Keep each task’s plan, branch, and intermediate reasoning local.

The important distinction is stable versus volatile. Formatting rules and approved commands may remain stable for months. A symbol’s callers can change in the next commit. Loading volatile facts into a permanent instruction file turns yesterday’s observation into tomorrow’s false authority.

Pi Skills and Prompt Templates

Pi loads the first recognized context file in each directory, preferring AGENTS.md and falling back to CLAUDE.md. It walks from ancestors toward the current directory and also supports global context. These files are suitable for stable project conventions, commands, and constraints.

Pi skills follow the Agent Skills standard. Pi scans Skill names and descriptions, then reads the full SKILL.md when a Skill is selected. Skills are appropriate for reusable multi-step procedures, specialized references, output schemas, and task-specific checks.

Prompt Templates are different. They are Markdown snippets invoked as filename-based slash commands. A template can expand a common prompt, but it does not become a Skill package with the same discovery and supporting-file behavior.

Sessions are JSONL trees. Compaction summarizes older turns so work can continue under context limits. That session record belongs to one conversation; it is not shared team repository memory.

Searches for Pi-coding-agent GitHub should resolve to the current first-party earendil-works/pi repository. Historical package and repository names can appear in third-party content, so pin links and versions when documenting extensions or Skills.

Use Pi layers this way:

• AGENTS.md: stable cross-tool conventions and commands;
• Pi-specific global or directory context: harness behavior that should always apply;
• Skill: an on-demand repository-analysis or review workflow;
• Prompt Template: a lightweight reusable prompt;
• session: task conversation and recoverable local state;
• extension/package: new runtime capability or adapter.

Claude Code CLAUDE.md, Skills, and Memory

The Pi-coding-agent GitHub source remains the authority for Pi behavior even when a cross-tool comparison is organized around Claude Code's context surfaces.

Claude Code reads CLAUDE.md as human-written persistent instructions. It supports nested files, rules, and @path imports. Anthropic’s documented compatibility pattern lets CLAUDE.md import AGENTS.md, which is useful when a repository also serves tools that read AGENTS.md directly.

Claude Code Skills are on-demand procedures. Their descriptions are available for selection while full bodies load when used. Legacy custom commands still work but are merged into the Skills model; “recipe” is therefore an editorial label rather than an official feature name.

Claude auto memory is Claude-written, per repository, and local to a machine. It can retain useful observations across local sessions and worktrees. It is not an organization-wide source of truth and can drift from current code. Treat it as a lead that needs verification.

Claude Code also exposes plugins, MCP, subagents, code-intelligence integrations, and fine-grained permission rules. These can improve retrieval and control. They do not make a material code claim true without evidence.

Keep CLAUDE.md concise and stable. Put specialized procedures in Skills so they load on demand. Put current structural relationships in source or an external index. Keep permission enforcement in actual permission rules rather than prose alone.

What Rules Cannot Express About Code

Rules can name architectural intent: “the API package must not depend on storage adapters,” or “generated clients are never edited directly.” They should not attempt to enumerate every current caller and test.

Large repositories contain relationships that are expensive and error-prone to maintain as prose:

• symbols defined and referenced across packages;
• registration and dependency-injection paths;
• schemas that generate clients or migrations;
• events and queues connecting services;
• tests covering contracts through indirect behavior;
• architecture decisions constraining a dependency;
• unresolved dynamic edges and failed parses.

A CLAUDE.md line that says “all payments are in packages/billing” becomes dangerous after a migration. A Pi Skill that hard-codes the same assumption has the same problem. Procedures should ask the current code or index where the path lives and require source verification.

Shared Repository Knowledge Layer

Build one tool-neutral evidence contract:

repository
indexed_commit
query
entities
relationships
source_locations
derivation
coverage_gaps
generated_at

The layer can be structured files, a language-server-backed index, or a code knowledge graph. Give Claude Code an MCP or CLI adapter. Give Pi a CLI or extension/package adapter because Pi does not document built-in MCP. Return the same schema to both tools.

The code knowledge graph or index proposed here is a shared external layer, operated by the team, for model-independent structural queries with revision-aware provenance.

Keep retrieval task-shaped. A request for impact analysis should return likely definitions, callers, schemas, tests, owners, and unknown edges—not a dump of the repository. Bind results to the task commit and reject them when the revisions differ.

Ordinary agents should query read-only. A separate reviewed job updates the index. Every relationship should cite current source, and agents should verify high-impact edges before planning edits. The shared layer reduces repeated discovery; it does not merge the tools’ private reasoning.

Add a small handoff object when work moves between harnesses. Record the task, repository commit, evidence queries, inspected paths, decisions, rejected alternatives, tests, and unresolved questions. Keep it declarative; do not attempt to serialize hidden reasoning. The receiving tool should re-open material files and mark any conclusion it cannot reproduce. This makes a Pi-to-Claude or Claude-to-Pi handoff auditable without pretending that a session transcript is portable memory.

Expire the handoff when its base commit or acceptance criteria changes, and keep replacement history for review.

Make every replacement explicit and reversible.

Treat handoff generation as a reviewed workflow. A convenience command may collect paths and test output, but a human or independent reviewer should approve material decisions before another tool inherits them.

Limits and Setup Risks

Cross-tool context fails in predictable ways:

• Pi and Claude Code can interpret the same prose differently.
• A Skill frontmatter field may have different permission semantics.
• A session summary can preserve a conclusion after its source changes.
• An index can miss reflection, generated code, or runtime configuration.
• Broad shared context can expose sensitive relationships.
• Duplicate Skills can resolve differently in each harness.

Test every shared asset in both tools. Record the loaded context files and Skill versions. Restrict the repository adapter by identity and path. Include “unknown” and “revision mismatch” fixtures. Require human review for architecture, security, data contracts, and destructive actions.

The smallest safe system is usually better: one neutral committed file, one tool-specific instruction layer per harness, a few well-tested Skills, and a read-only evidence adapter.

FAQ

Which context should be tool-specific?

Keep permission behavior, native commands, provider adapters, extension setup, and harness-specific workflow in tool-native files or Skills. Shared files should contain only neutral repository conventions that both tools can interpret safely.

Who maintains shared repo knowledge?

Assign a repository-context owner and an automated extraction service. Code owners review material schema or manual-fact changes. Task agents consume the layer read-only and report mismatches.

How should teams compare outputs?

Pin the same commit and task, require path-and-symbol evidence, score supported relationships and honest unknowns, and compare tool/file reads separately from correctness. Do not judge by prose confidence.

pi coding agent extensions

Pi extensions add runtime capabilities such as tools, commands, or integrations. Treat each extension as code: review its source, permissions, update path, and behavior before using it as a repository-context adapter.

Conclusion

Context engineering is lifecycle engineering. Put stable rules where they always load, procedures where they load on demand, task conversation in sessions, and volatile repository facts in a source-attributed layer. Pi and Claude Code can then share evidence without pretending to share one mind.