These examples document stable output shapes for CLI JSON commands and MCP tools. Values such as absolute paths, hashes, scores, timestamps, and line numbers vary by project and run. Arrays may contain more entries than shown.
Endpoint:
/api/ingest-history?limit=2
Output:
{
"db_path": "/demo/.codewell/codewell.sqlite3",
"runs": [
{
"id": 7,
"source_kind": "archive",
"source_value": "/imports/project.zip",
"library_root": "/demo-library",
"db_path": "/demo-library/workspaces/project/derived/codewell.sqlite3",
"materialized_root": "/demo-library/archives/project/source/project-main",
"manifest_path": null,
"cache_status": "hit_or_materialized",
"status": "failed",
"error_message": "indexing failed for /demo-library/archives/project/source/project-main: boom",
"started_at": "2026-05-13T05:00:00+00:00",
"finished_at": "2026-05-13T05:00:02+00:00",
"detail_command": "codewell ingest-history --db /demo-library/workspaces/project/derived/codewell.sqlite3 --run-id 7",
"next_step": "codewell ingest-history --library-root /demo-library --run-id 7 ; then retry `codewell index /imports/project.zip --library-root /demo-library`"
}
],
"events": []
}Notes:
detail_commandis the inspect command for one run.next_stepis the suggested command chain for failed ingest recovery.
Command:
codewell trace login_user --db .codewell/codewell.sqlite3 --source-lines 3Output:
{
"query": "login_user",
"db_path": "/demo/.codewell/codewell.sqlite3",
"matches": [
{
"path": "auth.py",
"absolute_path": "/demo/auth.py",
"name": "login_user",
"qualified_name": "login_user",
"kind": "function",
"line_start": 1,
"line_end": 2,
"source_excerpt": {
"start_line": 1,
"end_line": 2,
"lines": [
"1: def login_user(name: str) -> bool:",
"2: return bool(name)"
],
"truncated": false,
"lines_omitted": 0
}
}
],
"incoming_calls": [
{
"path": "app.py",
"absolute_path": "/demo/app.py",
"caller": "handle_login",
"callee": "login_user",
"line": 5
}
],
"outgoing_calls": [
{
"path": "auth.py",
"absolute_path": "/demo/auth.py",
"caller": "login_user",
"callee": "bool",
"line": 2
}
]
}Command:
codewell context "where is login handled?" \
--db .codewell/codewell.sqlite3 \
--budget 800 \
--response-mode debugOutput:
{
"query": "where is login handled?",
"db_path": "/demo/.codewell/codewell.sqlite3",
"token_budget": 800,
"token_estimate": 210,
"selected_files": [
{
"path": "app.py",
"absolute_path": "/demo/app.py",
"sha256": "example-sha256",
"score": -1.23,
"snippet": "def handle_login(name: str) -> str: ...",
"token_estimate": 72,
"symbols": [
{
"name": "handle_login",
"qualified_name": "handle_login",
"kind": "function",
"line_start": 4,
"line_end": 8
}
],
"imports": [
{
"module": "auth",
"name": "login_user",
"alias": null,
"line": 1
}
],
"call_edges": [
{
"caller": "handle_login",
"callee": "login_user",
"line": 5
}
],
"selection_reasons": [
"symbol hit: handle_login",
"body hit: login",
"call edge hit: handle_login -> login_user"
],
"metadata_truncated": false,
"symbols_omitted": 0,
"imports_omitted": 0,
"call_edges_omitted": 0
}
],
"selected_symbols": [
{
"name": "handle_login",
"qualified_name": "handle_login",
"kind": "function",
"line_start": 4,
"line_end": 8
}
],
"selection_explanation": [
"Matched 2 file(s) with SQLite FTS5.",
"Selected 1 file(s) within an estimated budget of 800 tokens.",
"Token estimates are approximate.",
"app.py: symbol hit: handle_login; body hit: login; call edge hit: handle_login -> login_user.",
"Included 1 symbol trace(s).",
"Included 1 agent-ready symbol neighborhood(s).",
"Included 1 related revision record(s)."
],
"related_revisions": [
{
"revision_id": 1,
"snippet_id": "snippet-auth",
"verification_state": "test_verified",
"explanation": "The target project uses pyjwt.",
"test_command": "pytest",
"applicability_notes": "Projects using pyjwt.",
"score": -0.75,
"applicability_signals": [
"query term matched explanation"
],
"applicability_warnings": []
}
],
"symbol_traces": [
{
"query": "handle_login",
"db_path": "/demo/.codewell/codewell.sqlite3",
"matches": [
{
"path": "app.py",
"absolute_path": "/demo/app.py",
"name": "handle_login",
"qualified_name": "handle_login",
"kind": "function",
"line_start": 4,
"line_end": 8,
"source_excerpt": {
"start_line": 2,
"end_line": 7,
"lines": [
"2: from auth import login_user",
"3: ",
"4: def handle_login(name: str) -> str:",
"5: if login_user(name):",
"6: return \"ok\"",
"7: return \"denied\""
],
"truncated": false,
"lines_omitted": 0
}
}
],
"incoming_calls": [],
"outgoing_calls": [
{
"path": "app.py",
"absolute_path": "/demo/app.py",
"caller": "handle_login",
"callee": "login_user",
"line": 5
}
]
}
],
"symbol_neighborhoods": [
{
"anchor_symbol": {
"name": "handle_login",
"qualified_name": "handle_login",
"kind": "function",
"line_start": 4,
"line_end": 8
},
"anchor_match": {
"path": "app.py",
"absolute_path": "/demo/app.py",
"name": "handle_login",
"qualified_name": "handle_login",
"kind": "function",
"line_start": 4,
"line_end": 8,
"source_excerpt": {
"start_line": 2,
"end_line": 7,
"lines": [
"2: from auth import login_user",
"3: ",
"4: def handle_login(name: str) -> str:",
"5: if login_user(name):",
"6: return \"ok\"",
"7: return \"denied\""
],
"truncated": false,
"lines_omitted": 0
}
},
"summary": "anchor handle_login [function]; calls login_user; callee defs in auth.py",
"incoming_calls": [],
"outgoing_calls": [
{
"path": "app.py",
"absolute_path": "/demo/app.py",
"caller": "handle_login",
"callee": "login_user",
"line": 5
}
],
"caller_definitions": [],
"callee_definitions": [
{
"path": "auth.py",
"absolute_path": "/demo/auth.py",
"name": "login_user",
"qualified_name": "login_user",
"kind": "function",
"line_start": 1,
"line_end": 2,
"source_excerpt": {
"start_line": 1,
"end_line": 2,
"lines": [
"1: def login_user(name: str) -> bool:",
"2: return bool(name)"
],
"truncated": false,
"lines_omitted": 0
}
}
]
}
],
"agent_brief": [
"Primary file: app.py with symbols handle_login.",
"anchor handle_login [function]; calls login_user; callee defs in auth.py",
"Revision memory: snippet-auth [test_verified] The target project uses pyjwt."
],
"diagnostics": {
"response_mode": "debug",
"query_terms": [
"where",
"is",
"login",
"handled"
],
"include_revisions": true,
"symbol_trace_limit": 4,
"trace_related_limit": 12,
"symbol_neighborhood_limit": 4,
"neighbor_definition_limit": 4,
"lexical_candidates": [
{
"path": "app.py",
"raw_score": -1.23,
"adjusted_score": -1.23,
"path_penalty": 0.0,
"selected": true,
"reasons": [
"symbol terms matched",
"snippet terms matched",
"selected for context"
]
},
{
"path": "tests/test_auth.py",
"raw_score": -0.82,
"adjusted_score": 11.18,
"path_penalty": 12.0,
"selected": false,
"reasons": [
"path terms matched",
"snippet terms matched",
"path penalty 12",
"outside selection window by 12.41"
]
}
],
"graph_expansion_file_count": 1,
"metadata_truncated_files": 0,
"stopped_reason": null
}
}MCP tools return a wrapper object around the same underlying model shapes.
Tool call arguments:
{
"query": "login",
"db_path": "/demo/.codewell/codewell.sqlite3",
"limit": 3
}Tool result:
{
"results": [
{
"path": "app.py",
"score": -1.23,
"snippet": "def handle_login(name: str) -> str: ...",
"symbols": [
"handle_login (function:4)"
]
}
]
}Tool call arguments:
{
"query": "where is login handled?",
"db_path": "/demo/.codewell/codewell.sqlite3",
"token_budget": 800,
"response_mode": "compact",
"include_project_documents": false
}Notes:
attached_documentsis a lightweight reference list for agents, not full document content.- The default context pack keeps this list intentionally small. Current limit: 4 references.
- Priority order is
symbollinks, thenfilelinks, then opt-inprojectlinks. - Project-linked documents remain opt-in through
include_project_documents.
Tool result:
{
"context_pack": {
"query": "where is login handled?",
"db_path": "/demo/.codewell/codewell.sqlite3",
"token_budget": 800,
"token_estimate": 210,
"selected_files": [
{
"path": "app.py",
"absolute_path": "/demo/app.py",
"sha256": "example-sha256",
"score": -1.23,
"snippet": "def handle_login(name: str) -> str: ...",
"token_estimate": 72,
"symbols": [],
"imports": [],
"call_edges": [],
"selection_reasons": [
"symbol hit: handle_login"
],
"metadata_truncated": false,
"symbols_omitted": 0,
"imports_omitted": 0,
"call_edges_omitted": 0
}
],
"selected_symbols": [],
"selection_explanation": [
"Matched 2 file(s) with SQLite FTS5.",
"Selected 1 file(s) within an estimated budget of 800 tokens.",
"Token estimates are approximate.",
"Included 1 manually linked document reference(s)."
],
"attached_documents": [
{
"document_id": "login-paper",
"title": "Login Flow Notes",
"path": ".codewell/docs/attached/login-paper.pdf",
"type": "paper",
"relation": "explained_by",
"source_type": "symbol",
"source_id": "login_user",
"target_locator": "sec-3",
"confidence": 0.9,
"managed_copy": true
}
],
"related_revisions": [],
"symbol_traces": [
{
"query": "handle_login",
"db_path": "/demo/.codewell/codewell.sqlite3",
"matches": [
{
"path": "app.py",
"absolute_path": "/demo/app.py",
"name": "handle_login",
"qualified_name": "handle_login",
"kind": "function",
"line_start": 4,
"line_end": 8,
"source_excerpt": {
"start_line": 2,
"end_line": 7,
"lines": [
"2: from auth import login_user",
"3: ",
"4: def handle_login(name: str) -> str:",
"5: if login_user(name):",
"6: return \"ok\"",
"7: return \"denied\""
],
"truncated": false,
"lines_omitted": 0
}
}
],
"incoming_calls": [],
"outgoing_calls": [
{
"path": "app.py",
"absolute_path": "/demo/app.py",
"caller": "handle_login",
"callee": "login_user",
"line": 5
}
]
}
],
"symbol_neighborhoods": [
{
"anchor_symbol": {
"name": "handle_login",
"qualified_name": "handle_login",
"kind": "function",
"line_start": 4,
"line_end": 8
},
"anchor_match": {
"path": "app.py",
"absolute_path": "/demo/app.py",
"name": "handle_login",
"qualified_name": "handle_login",
"kind": "function",
"line_start": 4,
"line_end": 8,
"source_excerpt": {
"start_line": 2,
"end_line": 7,
"lines": [
"2: from auth import login_user",
"3: ",
"4: def handle_login(name: str) -> str:",
"5: if login_user(name):",
"6: return \"ok\"",
"7: return \"denied\""
],
"truncated": false,
"lines_omitted": 0
}
},
"summary": "anchor handle_login [function]; calls login_user; callee defs in auth.py",
"incoming_calls": [],
"outgoing_calls": [
{
"path": "app.py",
"absolute_path": "/demo/app.py",
"caller": "handle_login",
"callee": "login_user",
"line": 5
}
],
"caller_definitions": [],
"callee_definitions": [
{
"path": "auth.py",
"absolute_path": "/demo/auth.py",
"name": "login_user",
"qualified_name": "login_user",
"kind": "function",
"line_start": 1,
"line_end": 2,
"source_excerpt": {
"start_line": 1,
"end_line": 2,
"lines": [
"1: def login_user(name: str) -> bool:",
"2: return bool(name)"
],
"truncated": false,
"lines_omitted": 0
}
}
]
}
],
"agent_brief": [
"Primary file: app.py with symbols handle_login.",
"anchor handle_login [function]; calls login_user; callee defs in auth.py",
"Attached doc: Login Flow Notes [paper] via symbol:login_user (explained_by)."
],
"diagnostics": {
"response_mode": "compact",
"query_terms": [
"where",
"is",
"login",
"handled"
],
"include_revisions": false,
"symbol_trace_limit": 1,
"trace_related_limit": 4,
"symbol_neighborhood_limit": 1,
"neighbor_definition_limit": 1,
"lexical_candidates": [
{
"path": "app.py",
"raw_score": -1.23,
"adjusted_score": -1.23,
"path_penalty": 0.0,
"selected": true,
"reasons": [
"symbol terms matched",
"snippet terms matched",
"selected for context"
]
}
],
"graph_expansion_file_count": 0,
"metadata_truncated_files": 0,
"attached_documents_total_matches": 1,
"attached_documents_omitted": 0,
"stopped_reason": null
}
}
}Tool result from record_revision:
{
"revision": {
"id": 2,
"snippet_id": "snippet-auth",
"failure_id": 1,
"fix_diff": "Use pyjwt import.",
"explanation": "The target project uses pyjwt.",
"test_command": "pytest",
"test_result": "1 passed",
"verification_state": "test_verified",
"applicability_notes": "Projects using pyjwt.",
"created_at": "2026-05-11T00:00:00+00:00"
}
}Tool result from search_revision_memory:
{
"results": [
{
"revision_id": 2,
"snippet_id": "snippet-auth",
"verification_state": "test_verified",
"explanation": "The target project uses pyjwt.",
"test_command": "pytest",
"applicability_notes": "Projects using pyjwt.",
"score": -0.75
}
]
}