Context Engineering for Claudex

Claudex context engineering means giving the model current, scoped repository evidence instead of assuming that changing the model creates repository knowledge. In this article, Claudex specifically means the unofficial, MIT-licensed liuzhao1225/claudex wrapper—not the several unrelated projects that share the name.

As of July 17, 2026, this Claudex project was only days old. It launched the installed Claude Code client through a localhost CLIProxyAPI gateway and selected gpt-5.6-sol by default. Neither OpenAI nor Anthropic documents or endorses this route, so teams should treat it as an experimental integration and keep their repository knowledge portable.

What Claudex Context Engineering Means

Claudex is a routing wrapper, not a new model or context engine.

Its launch script verifies that the chosen model appears in the proxy's catalog, sets Claude Code gateway and model environment variables, and then executes the existing claude binary. The default identifier is gpt-5.6-sol. OpenAI's official Codex model page currently lists the same identifier and describes Sol as its flagship GPT-5.6 option for complex coding and other demanding work.

That confirms the model name in native Codex. It does not establish feature parity through a third-party protocol translator, benchmark Claudex on repository tasks, or show that every ChatGPT account can use the route.

The useful mental model has four separate layers:

Layer	Responsibility	Source of truth
Client	Tools, file access, instructions, session flow	Installed Claude Code version
Route	Authentication and protocol translation	Claudex plus its pinned CLIProxyAPI release
Model	Reasoning over supplied context	Selected upstream model and settings
Repository knowledge	Architecture, dependencies, ownership, tests	Maintained project artifacts and current source

Context engineering operates mainly in the fourth layer. A stronger model may interpret evidence better, but it cannot recover a private service boundary, generated-code rule, or migration constraint that the workflow never supplies.

Before adoption, run a controlled task on both the native client and the Claudex route. Record the exact versions, model identifier, reasoning setting, files opened, searches performed, plan accuracy, test selection, and review corrections. This tests the complete workflow instead of attributing every result to the model name.

Organize CLAUDE.md and Project Rules

Use CLAUDE.md for stable instructions that should shape most work in the repository.

Anthropic's Claude Code memory documentation says project instructions can live in ./CLAUDE.md or ./.claude/CLAUDE.md. Ancestor instruction files load at launch, while files in subdirectories load when Claude reads within those areas. Modular files under .claude/rules/ can also be scoped to particular paths.

Because Claudex ultimately executes the installed claude client, normal instruction discovery should remain client-side behavior. That is an inference from the wrapper's source, not a Claudex compatibility guarantee. Test it after upgrades, especially when the gateway or Claude Code protocol changes.

Keep the root file concise and operational:

• list the correct build, lint, test, and type-check commands;
• name generated, vendored, and migration-controlled paths;
• identify architecture indexes and package owners;
• define approval points for schemas, permissions, and public interfaces;
• require source inspection before repository-wide edits;
• state how to report uncertainty and verification results.

Do not paste a changing dependency inventory into global instructions. Anthropic describes these files as context rather than enforced configuration and recommends concise, specific rules, with a target below 200 lines per file. Put enforceable restrictions in permissions, hooks, or external review controls.

If a team standardizes on AGENTS.md across tools, avoid two hand-maintained copies. Claude Code reads CLAUDE.md, not AGENTS.md, but its official documentation supports importing AGENTS.md from CLAUDE.md. Add Claude-specific guidance only where the client truly needs it.

A practical root rule might require a pre-edit report:

Before a cross-package change, report:
1. entry point and owning package;
2. direct and transitive dependency path;
3. generated artifacts and schema sources;
4. focused tests and rollback path;
5. unresolved assumptions requiring approval.

This rule directs the agent toward evidence without freezing today's repository map into a permanent prompt.

Add Architecture and Dependency Signals

Architecture context should reveal relationships that file names and local imports cannot explain.

Maintain a short system overview, package boundaries, key data flows, architecture decision records, ownership rules, generated-code paths, and deployment constraints. Each artifact should identify its maintainer, relevant source revision, and review trigger. A polished diagram with no date or owner is a weak source because the agent cannot judge whether it describes the current system.

Dependency signals should connect intent to implementation. For a proposed change, the agent needs to locate:

• the entry point and authoritative implementation;
• callers, consumers, and runtime dependencies;
• schemas or generators that own derived files;
• tests that observe the changed behavior;
• security, migration, and rollback boundaries.

Static rules point to evidence; current source and dependency signals determine the plan.

Use progressive disclosure. The root instructions should point to an architecture index, while package-local rules and task-specific retrieval provide detail only when relevant. This leaves more context for current code and reduces the chance that an unrelated design record dominates the task.

For a broader method that is independent of the model route, see how to help Claude Code understand a complex repository. The same project knowledge should remain useful if the team later returns to native Claude models or moves the task to another coding agent.

Use Code Graphs for Cross-File Planning

A code graph is useful when cross-file relationships exceed what a compact CLAUDE.md can maintain.

The graph can represent symbols, files, packages, routes, schemas, tests, owners, and architecture records as nodes. Typed edges can express imports, calls, generation, coverage, ownership, or documented rationale. An agent can query those relationships to select a small evidence set before reading the source.

For a multi-file change, use a graph-assisted planning loop:

1. Define the behavior and entry point instead of starting with a broad repository scan.
2. Query inbound and outbound dependency paths around the affected symbol or package.
3. Identify tests, generated artifacts, schemas, and owners connected to that path.
4. Open the current source files and verify every material edge.
5. Draft the plan with confirmed facts separated from inference.
6. Run focused tests, then expand verification according to the impact radius.

The graph is a navigation and impact-analysis layer, not approval evidence by itself. Record the indexed commit, generation time, parser coverage, ignored paths, and inferred-edge rules. Refresh it after structural changes or reject results that are older than the source under review.

Claudex does not create this graph. A separate repository tool must build and expose it through commands, files, or another supported integration. Graphify is one option for generating a code knowledge graph, but the workflow should still verify proposed paths against current source and tests.

This separation also prevents model lock-in. The same maintained graph and architecture index can support a GPT-5.6 Sol route, native Claude Code, and a shared multi-agent workflow. The companion guide to sharing repository context across coding agents explains how to keep common evidence separate from tool-specific instructions.

Limits and Staleness Risks

The largest Claudex risk is not prompt length; it is treating an experimental route as stable infrastructure.

Anthropic's gateway documentation states that it does not endorse, maintain, or audit third-party gateways and does not support routing Claude Code to non-Claude models through a gateway. It also warns that client features can break when a gateway fails to pass through newer protocol capabilities.

Claudex reduces some local exposure by binding its proxy to 127.0.0.1, pinning a CLIProxyAPI build, and storing a local token. “Localhost-only” does not mean source code stays on the device. The proxy still sends prompts, credentials, tool results, and selected code to upstream services. Review the proxy, provider data controls, and repository sensitivity before use.

Verify the route and the evidence layer separately before approving repository-wide changes.

Use this release gate:

• pin the Claudex, CLIProxyAPI, and Claude Code versions;
• verify the exact model identifier rather than accepting a silent fallback;
• inspect the effective project instructions and permission boundary;
• refresh architecture and graph artifacts against the working commit;
• test subagent behavior and tool compatibility explicitly;
• compare a representative repository task with a supported native workflow;
• review current OpenAI terms, plan guidance, and Anthropic gateway documentation;
• require human approval for dependency-wide, permission, schema, or migration changes.

Passing CI in the Claudex repository is useful but limited evidence. Its workflow checks shell code, unit behavior, and pinned dependencies; model-catalog responses and the Claude executable are mocked in relevant tests. That is not an independent evaluation of protocol parity, model quality, repository understanding, or account safety.

Staleness applies to every layer. Models and account availability change, gateway translations lag client features, CLAUDE.md accumulates obsolete rules, architecture documents drift, and graphs age after merges. Attach an owner and event-driven refresh trigger to each artifact, then make the agent report its evidence timestamps.

FAQ

Who should maintain context files?

Platform or developer-experience owners should maintain shared workflow rules. Architecture owners should review system boundaries and decision records. Package teams should maintain local commands, schemas, and tests. Every artifact needs an owner, authority level, and refresh trigger; no single person should silently redefine repository-wide permissions.

What should not be duplicated in prompts?

Do not duplicate large source files, secrets, volatile dependency lists, generated output, or the full text of architecture records. Keep stable directives in project rules, retrieve current relationships from maintained artifacts, and cite the authoritative files in the task plan. Duplicate facts become contradictory facts after the next merge.

How should subagents share repo knowledge?

Give subagents a common evidence bundle: task goal, working commit, architecture index, relevant graph query, source paths, tests, permissions, and unresolved assumptions. Keep role-specific instructions separate. With Claudex, also verify CLAUDE_CODE_SUBAGENT_MODEL and actual subagent behavior instead of assuming that every Claude-specific capability translates unchanged.

Conclusion

Context engineering for Claudex is valuable only when the repository knowledge survives the model route.

Treat liuzhao1225/claudex as an unofficial, fast-changing bridge to GPT-5.6 Sol. Keep stable constraints in concise CLAUDE.md rules, retrieve architecture and dependency evidence on demand, use code graphs to narrow cross-file planning, and verify every material relationship against current source and tests.

The decision rule is straightforward: if the team cannot reproduce the plan with pinned versions, dated context, and an explicit approval path, improve the knowledge and verification layer before trusting the model swap.