SmallCode

To prevent small models from losing quality due to context dumping, follow the Iterative Retrieval Ladder. Instead of reading entire files immediately, climb the ladder and stop as soon as you have sufficient context. This approach prioritizes cheaper memory and search operations over expensive file reads.

The Ladder Steps:

1. memory_load: Retrieve past decisions, gotchas, and workflows.
2. search / graph_search: Find relevant paths and code snippets.
3. read_file: Perform a single, targeted file read.
4. Full repo reads: Use this only as a last resort.

When executing the brainstorming skill, the following rules must be strictly followed:

• Contextual Search: Always perform a context search before proposing ideas.
• Minimum Approaches: You must provide at least three approaches.
• Mandatory Stop: Step 6 (waiting for confirmation) is not optional. Skipping this step defeats the purpose of the skill.
• Handling Rejections: If the user rejects all three proposed approaches, do not immediately generate more. Instead, ask the user what is missing or what they are looking for to refine the next set of proposals.

Escalation is an opt-in mechanism that allows SmallCode to call a powerful cloud model (Anthropic, OpenAI, or DeepSeek) when a local model fails to complete a task after exhausting retries and decomposition strategies.

Configuration and Behavior

• Provider Preference: The engine detects keys in this order: Anthropic > OpenAI > DeepSeek.
• Format Conversion: The system automatically converts conversation history to the provider's native format (e.g., converting OpenAI tool_calls to Anthropic tool_use/tool_result blocks).
• Safety Limits: There is a default session cap of five escalations to prevent unexpected API costs.
• Requirement: The feature is dormant unless a cloud API key is configured. If no key is found, canEscalate() returns false.

SmallCode uses a patch primitive for file edits instead of full-file rewrites. This is designed for small models that struggle with long-form generation.

The Patch Mechanism

• Mechanism: A search-and-replace operation where the old_str must match exactly one location in the target file.
• Fallback: If a patch fails because the old_str no longer matches (due to previous edits shifting content), the system uses a semantic merge fallback. This asks the model to merge the intended change into the current file and return the entire corrected file.
• Read-before-write Guard: To prevent models from overwriting files with incorrect content, the system refuses the first attempt to write to a file that hasn't been read during the current session. A second attempt is permitted if the model needs to perform a full replacement.

SmallCode uses a hybrid search approach to retrieve code snippets without requiring an external vector database or cloud embeddings:

1. BM25 Lexical Search: Searches over identifiers, paths, symbols, tags, and snippet text. Ideal for exact API names and framework constructs.
2. Local Hashed-Vector Similarity: A dependency-free vector search over snippet text that helps match related naming patterns even when exact words differ.
3. Hybrid Ranking: Combines BM25 and vector scores to inject the top relevant snippets into the model context.

This process is optimized for speed and local execution.

When debugging, adhere to these strict rules to ensure reliability:

• Never skip step 1: Always search prior context first.
• Never fix without a test: A fix is not valid until confirmed by a test.
• Reproduction is mandatory: If you cannot reproduce the bug in the reproduction step, you do not yet understand the issue.

SmallCode's intelligence is defined using MarrowScript. A single .marrow declaration compiles into a production-ready TypeScript runtime that provides advanced features like prompt caching, structured traces, tier-based routing, token budget enforcement, and automatic validation/repair.

To enable structured traces (trace_id/span_id) for every LLM call, set the environment variable SMALLCODE_COGNITION_LOG=stderr.

prompt classify_task_type(user_message: string) {
  model: TinyClassifier
  timeout: 3s
  cache: { key: hash(user_message), ttl: 10m }
  retry: { max_attempts: 2, backoff: fixed, interval: 100ms }
  constraints: [output in ["coding", "editing", "search", ...]]
}

By default, bash calls share a long-lived shell process, allowing state like cd, environment variables, and shell variables to persist across multiple calls.

To disable this behavior (making every call a fresh process), set SMALLCODE_SHELL_PERSIST=false.

Note: SmallCode includes optional cwd-containment to prevent cd or other escapes from leaving the project root.