Skip to content

Context7 Platform -- Up-to-date docs for AI agents

Handle Codex CLI sandbox DNS failures in setup (#2449)

Fahreddin Özcan33f233809231
diff --git a/.changeset/five-swans-learn.md b/.changeset/five-swans-learn.md
new file mode 100644
index 00000000..1643f68b
--- /dev/null
+++ b/.changeset/five-swans-learn.md
@@ -0,0 +1,5 @@
+---
+"ctx7": patch
+---
+
+Add Codex-specific CLI setup guidance so generated rules and the installed `find-docs` skill tell Codex to rerun Context7 CLI requests outside the default sandbox after DNS or network failures.
diff --git a/packages/cli/src/commands/setup.ts b/packages/cli/src/commands/setup.ts
index ad92902f..dfbfe54e 100644
--- a/packages/cli/src/commands/setup.ts
+++ b/packages/cli/src/commands/setup.ts
@@ -22,7 +22,7 @@ import {
getAgent,
detectAgents,
} from "../setup/agents.js";
-import { getRuleContent } from "../setup/templates.js";
+import { customizeSkillFilesForAgent, getRuleContent } from "../setup/templates.js";
import {
readJsonConfig,
mergeServerEntry,
@@ -407,7 +407,8 @@ async function setupCliAgent(
: join(process.cwd(), agent.skill.dir("project"));
let skillStatus: string;
try {
- await installSkillFiles("find-docs", downloadData.files, skillDir);
+ const files = customizeSkillFilesForAgent(agentName, "find-docs", downloadData.files);
+ await installSkillFiles("find-docs", files, skillDir);
skillStatus = "installed";
} catch (err) {
skillStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;
diff --git a/packages/cli/src/setup/templates.ts b/packages/cli/src/setup/templates.ts
index e10faeda..26b96140 100644
--- a/packages/cli/src/setup/templates.ts
+++ b/packages/cli/src/setup/templates.ts
@@ -34,6 +34,7 @@ If a command fails with a quota error, inform the user and suggest \`npx ctx7@la
`;
const CURSOR_FRONTMATTER = `---\nalwaysApply: true\n---\n\n`;
+const CODEX_CLI_SANDBOX_GUIDANCE = `Run Context7 CLI requests outside Codex's default sandbox. If a Context7 CLI command fails with DNS or network errors such as ENOTFOUND, host resolution failures, or fetch failed, rerun it outside the sandbox instead of retrying inside the sandbox.`;
export type RuleMode = "mcp" | "cli";
@@ -52,6 +53,43 @@ async function fetchRule(filename: string, fallback: string): Promise<string> {
export async function getRuleContent(mode: RuleMode, agent: string): Promise<string> {
const [filename, fallback] =
mode === "mcp" ? ["context7-mcp.md", FALLBACK_MCP] : ["context7-cli.md", FALLBACK_CLI];
- const body = await fetchRule(filename, fallback);
+ let body = await fetchRule(filename, fallback);
+
+ if (mode === "cli" && agent === "codex" && !body.includes(CODEX_CLI_SANDBOX_GUIDANCE)) {
+ body = `${body.trimEnd()}\n${CODEX_CLI_SANDBOX_GUIDANCE}\n`;
+ }
+
return agent === "cursor" ? `${CURSOR_FRONTMATTER}${body}` : body;
}
+
+export function customizeSkillFilesForAgent(
+ agent: string,
+ skillName: string,
+ files: Array<{ path: string; content: string }>
+): Array<{ path: string; content: string }> {
+ if (agent !== "codex" || skillName !== "find-docs") {
+ return files;
+ }
+
+ return files.map((file) => {
+ if (file.path !== "SKILL.md" || file.content.includes(CODEX_CLI_SANDBOX_GUIDANCE)) {
+ return file;
+ }
+
+ const marker = "## Step 1: Resolve a Library";
+ const guidance = `${CODEX_CLI_SANDBOX_GUIDANCE}\n\n`;
+
+ if (file.content.includes(marker)) {
+ return {
+ ...file,
+ content: file.content.replace(marker, `${guidance}${marker}`),
+ };
+ }
+
+ const separator = file.content.endsWith("\n") ? "\n" : "\n\n";
+ return {
+ ...file,
+ content: `${file.content}${separator}${CODEX_CLI_SANDBOX_GUIDANCE}\n`,
+ };
+ });
+}