Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Local repository maps, code search and symbol references for coding agents. Code

## Published beta: 2.3.1-beta.0 (stable: 2.2.0)

As checked on **4 November 2026**, npm `beta` points to **`2.3.1-beta.0`**, while npm `latest` remains **`2.2.0`**. The beta requires **Node.js 22 or newer**. An unpinned `npx -y codebase-context` may use an already installed local version; without one, it resolves npm `latest` (currently the stable `2.2.0`). To select the published beta explicitly, use `npx -y codebase-context@2.3.1-beta.0 --version`. A source checkout or a local tarball is separate from a verified registry release.
As checked on **6 November 2026**, npm `beta` points to **`2.3.1-beta.0`**, while npm `latest` remains **`2.2.0`**. The beta requires **Node.js 22 or newer**. An unpinned `npx -y codebase-context` may use an already installed local version; without one, it resolves npm `latest` (currently the stable `2.2.0`). To select the published beta explicitly, use `npx -y codebase-context@2.3.1-beta.0 --version`. A source checkout or a local tarball is separate from a verified registry release.

**Fresh beta indexes use keyword search without downloading an embedding or reranker model.** Existing indexes keep their recorded mode. Semantic indexing is an explicit option; its optional runtimes and model downloads are separate from the default path.

Expand Down Expand Up @@ -39,6 +39,12 @@ node /path/to/codebase-context/dist/index.js init --client codex --root /path/to

The wizard recognizes Claude Code, Codex, Cursor and OpenCode. It saves the Node binary and package entrypoint that ran setup. If that installation or its npx cache is moved or removed, rerun setup. Writing a config does not prove that a native client connected or completed a coding task.

For manual Codex registration, the CLI help selects the published beta explicitly:

```bash
codex mcp add codebase-context -- npx -y codebase-context@2.3.1-beta.0
```

After registration, restart the client and ask:

> Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project, wait for indexing if needed, and open the relevant source files.
Expand Down
20 changes: 19 additions & 1 deletion src/cli-formatters.ts
Original file line number Diff line number Diff line change
Expand Up @@ -273,11 +273,11 @@
lines.push('');

const boxLines = drawBox('Team Patterns', lines, BOX_WIDTH);
console.log('');

Check warning on line 276 in src/cli-formatters.ts

View workflow job for this annotation

GitHub Actions / Quality Checks

Unexpected console statement. Only these console methods are allowed: warn, error
for (const l of boxLines) {
console.log(l);

Check warning on line 278 in src/cli-formatters.ts

View workflow job for this annotation

GitHub Actions / Quality Checks

Unexpected console statement. Only these console methods are allowed: warn, error
}
console.log('');

Check warning on line 280 in src/cli-formatters.ts

View workflow job for this annotation

GitHub Actions / Quality Checks

Unexpected console statement. Only these console methods are allowed: warn, error
}

export function formatSearch(
Expand All @@ -287,7 +287,13 @@
intent?: string
): void {
const g = getGlyphs();
const { searchQuality: quality, preflight, results, relatedMemories: memories } = data;
const {
searchQuality: quality,
sourceCoverage,
preflight,
results,
relatedMemories: memories
} = data;

const boxLines: string[] = [];

Expand All @@ -303,6 +309,18 @@
}
}

if (sourceCoverage && sourceCoverage.status !== 'current') {
boxLines.push(
`Source coverage: ${sourceCoverage.status}; checked ${sourceCoverage.checkedFiles} files, skipped ${sourceCoverage.skippedFiles}.`
);
if (sourceCoverage.candidateBudgetExhausted) {
boxLines.push('Search stopped early (candidate budget exhausted); narrow the query.');
}
if (sourceCoverage.refreshAction) {
boxLines.push(`Next: ${sourceCoverage.refreshAction}`);
}
}

if (preflight && showPreflight) {
const readyLabel = preflight.ready ? 'YES' : 'NO';
boxLines.push(`Ready to edit: ${readyLabel}`);
Expand Down Expand Up @@ -364,17 +382,17 @@
const boxTitle =
titleParts.length > 0 ? `Search: ${titleParts.join(` ${g.box.h.repeat(3)} `)}` : 'Search';

console.log('');

Check warning on line 385 in src/cli-formatters.ts

View workflow job for this annotation

GitHub Actions / Quality Checks

Unexpected console statement. Only these console methods are allowed: warn, error
if (boxLines.length > 0) {
const boxOut = drawBox(boxTitle, boxLines, BOX_WIDTH);
for (const l of boxOut) {
console.log(l);

Check warning on line 389 in src/cli-formatters.ts

View workflow job for this annotation

GitHub Actions / Quality Checks

Unexpected console statement. Only these console methods are allowed: warn, error
}
console.log('');

Check warning on line 391 in src/cli-formatters.ts

View workflow job for this annotation

GitHub Actions / Quality Checks

Unexpected console statement. Only these console methods are allowed: warn, error
} else if (quality) {
const status = quality.status === 'ok' ? 'ok' : 'low confidence';
console.log(` ${results?.length ?? 0} results ${g.dot} quality: ${status}`);

Check warning on line 394 in src/cli-formatters.ts

View workflow job for this annotation

GitHub Actions / Quality Checks

Unexpected console statement. Only these console methods are allowed: warn, error
console.log('');

Check warning on line 395 in src/cli-formatters.ts

View workflow job for this annotation

GitHub Actions / Quality Checks

Unexpected console statement. Only these console methods are allowed: warn, error
}

if (results && results.length > 0) {
Expand All @@ -391,8 +409,8 @@
if (trendPart) metaParts.push(trendPart);
if (r.relationships?.hasTests) metaParts.push('has tests');

console.log(`${i + 1}. ${file}`);

Check warning on line 412 in src/cli-formatters.ts

View workflow job for this annotation

GitHub Actions / Quality Checks

Unexpected console statement. Only these console methods are allowed: warn, error
console.log(` ${metaParts.join(` ${g.dot} `)}`);

Check warning on line 413 in src/cli-formatters.ts

View workflow job for this annotation

GitHub Actions / Quality Checks

Unexpected console statement. Only these console methods are allowed: warn, error

const summary = r.summary ?? '';
if (summary) {
Expand Down
5 changes: 4 additions & 1 deletion src/cli-init.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ import { checkbox } from '@inquirer/prompts';
import { homedir } from 'node:os';
import { constants } from 'node:fs';

export const CODEX_BETA_SETUP_COMMAND =
'codex mcp add codebase-context -- npx -y codebase-context@2.3.1-beta.0';

export type Client = (typeof CLIENTS)[number]['id'];

export type McpConfigResult = { kind: 'file'; path: string; content: string };
Expand Down Expand Up @@ -507,7 +510,7 @@ function printInitUsage(): void {
console.log(
'Each config saves this Node binary and the package file from the npx cache, plus the project folder.'
);
console.log('Codex setup line: codex mcp add codebase-context -- npx -y codebase-context');
console.log(`Codex beta setup line: ${CODEX_BETA_SETUP_COMMAND}`);
console.log(
' --client <name> Choose a tool (repeatable): ' +
CLIENTS.map((client) => client.id).join(', ')
Expand Down
6 changes: 3 additions & 3 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ import { GenericAnalyzer } from './analyzers/generic/index.js';
import { formatJson } from './cli-formatters.js';
import { handleMemoryCli } from './cli-memory.js';
export { handleMemoryCli } from './cli-memory.js';
import { handleInitCli } from './cli-init.js';
import { CODEX_BETA_SETUP_COMMAND, handleInitCli } from './cli-init.js';
import { handleMapCli } from './cli-map.js';
import { loadProjectConfig } from './server/config.js';
import { cliProjectOptions } from './cli-project-options.js';
Expand Down Expand Up @@ -91,8 +91,8 @@ function printUsage(): void {
console.log(' --version Print the package version');
console.log(' --help Show this help');
console.log('');
console.log('Codex setup line:');
console.log(' codex mcp add codebase-context -- npx -y codebase-context');
console.log('Codex beta setup line:');
console.log(` ${CODEX_BETA_SETUP_COMMAND}`);
console.log('');
console.log('Environment:');
console.log(' CODEBASE_ROOT Project root path (default: cwd for CLI only)');
Expand Down
2 changes: 1 addition & 1 deletion tests/cli-init.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -657,7 +657,7 @@ describe('handleInitCli', () => {
try {
await handleInitCli(['--help']);
expect(log.mock.calls.flat().join('\n')).toContain(
'codex mcp add codebase-context -- npx -y codebase-context'
'codex mcp add codebase-context -- npx -y codebase-context@2.3.1-beta.0'
);
} finally {
log.mockRestore();
Expand Down
122 changes: 122 additions & 0 deletions tests/cli.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,128 @@ describe('CLI', () => {
expect(toolMocks.dispatchTool).not.toHaveBeenCalled();
});

it('help gives the same pinned beta setup command as the README', async () => {
await handleCliCommand(['--help']);

const command = 'codex mcp add codebase-context -- npx -y codebase-context@2.3.1-beta.0';
const output = logSpy.mock.calls.map((call) => String(call[0] ?? '')).join('\n');
expect(output).toContain(command);
expect(await fs.readFile(new URL('../README.md', import.meta.url), 'utf8')).toContain(command);
expect(cliContextMocks.loadProjectConfig).not.toHaveBeenCalled();
expect(toolMocks.dispatchTool).not.toHaveBeenCalled();
});

it.each([
{ results: [] },
{ results: [{ file: 'src/example.ts:1-3', summary: 'Example', score: 0.2 }] }
])('discloses exhausted search coverage with $results.length results', async ({ results }) => {
toolMocks.dispatchTool.mockResolvedValue({
content: [
{
type: 'text',
text: JSON.stringify({
status: 'success',
searchQuality: { status: 'low_confidence', confidence: 0.2 },
sourceCoverage: {
status: results.length ? 'partial' : 'no_fresh_results',
checkedFiles: 30,
skippedFiles: 0,
candidateBudgetExhausted: true
},
results
})
}
]
});

await handleCliCommand(['search', '--query', 'example']);

const output = logSpy.mock.calls
.map((call) => String(call[0] ?? ''))
.join('\n')
.replace(/[│|]/g, '')
.replace(/\s+/g, ' ');
expect(output).toContain('checked 30 files');
expect(output).toContain('Search stopped early');
expect(output).toContain('candidate budget exhausted');
expect(output).toContain('narrow the query');
});

it('reports skipped search sources without claiming the candidate budget was exhausted', async () => {
toolMocks.dispatchTool.mockResolvedValue({
content: [
{
type: 'text',
text: JSON.stringify({
status: 'success',
searchQuality: { status: 'low_confidence', confidence: 0 },
sourceCoverage: {
status: 'partial',
checkedFiles: 2,
skippedFiles: 1,
refreshAction: 'Refresh changed sources, then retry.'
},
results: []
})
}
]
});

await handleCliCommand(['search', '--query', 'example']);

const output = logSpy.mock.calls
.map((call) => String(call[0] ?? ''))
.join('\n')
.replace(/[│|]/g, '')
.replace(/\s+/g, ' ');
expect(output).toContain('checked 2 files, skipped 1');
expect(output).toContain('Refresh changed sources, then retry.');
expect(output).not.toContain('Search stopped early');
});

it('does not claim an early stop for current search coverage', async () => {
toolMocks.dispatchTool.mockResolvedValue({
content: [
{
type: 'text',
text: JSON.stringify({
status: 'success',
searchQuality: { status: 'low_confidence', confidence: 0.2 },
sourceCoverage: { status: 'current', checkedFiles: 2, skippedFiles: 0 },
results: []
})
}
]
});

await handleCliCommand(['search', '--query', 'example']);

const output = logSpy.mock.calls.map((call) => String(call[0] ?? '')).join('\n');
expect(output).not.toContain('Search stopped early');
expect(output).toContain('low confidence');
});

it('preserves the raw search coverage response with --json', async () => {
const payload = {
status: 'success',
searchQuality: { status: 'low_confidence', confidence: 0.2 },
sourceCoverage: {
status: 'partial',
checkedFiles: 30,
skippedFiles: 0,
candidateBudgetExhausted: true
},
results: []
};
toolMocks.dispatchTool.mockResolvedValue({
content: [{ type: 'text', text: JSON.stringify(payload) }]
});

await handleCliCommand(['search', '--query', 'example', '--json']);

expect(JSON.parse(String(logSpy.mock.calls.at(-1)?.[0]))).toEqual(payload);
});

it('search dispatches with typed args', async () => {
toolMocks.dispatchTool.mockResolvedValue({
content: [{ type: 'text', text: JSON.stringify({ ok: true }) }]
Expand Down
Loading