DOCSEARCHbyAlgolia
Submit Docs

Forge Documentation

repository·main·Indexed 27 days ago

https://github.com/tailcallhq/forgecode

An AI-enhanced terminal development environment that integrates coding agents via a TUI, CLI, or ZSH plugin. Forge enables developers to perform refactoring, debugging, and git operations using natural language. The documentation covers installation, AI provider configuration, interactive TUI usage, and the forge_select crate for terminal interactions. It also includes detailed guides on running and extending semantic search quality evaluations using the forge_api (v0.1.0) and LLM judges.

Tokens
39.3K
Snippets
80
Records
256
Agent score
91%

What's inside Forge

  1. Understand Context Compaction Logic

    main

    Context compaction in Forge is used to manage long conversation histories by summarizing parts of the context. The logic identifies sequences of assistant messages and replaces them with a concise summary to save tokens and maintain context relevance.

    Key behaviors:

    • Targeted Compression: Instead of compressing the entire context at once, the system identifies the first continuous sequence of 2 or more consecutive assistant messages.
    • Message Preservation: User messages and single assistant messages are preserved in their original positions to maintain conversation flow.
    • Incremental Processing: Only one compressible sequence is processed per call to compact_context. Subsequent sequences can be compressed in later iterations.

  2. Understand Forge Configuration Error Handling

    main

    Forge is transitioning from a lazy, silent-error configuration model to an eager, error-surfaced model.

    Old Behavior (Lazy): ForgeConfig was read from disk only when first requested. If the configuration file was corrupt or invalid, errors were swallowed, and the system silently defaulted to ForgeConfig::default() (all-zero values). This caused silent failures in tool limits and agent parameters.

    New Behavior (Eager): ForgeConfig is read once at application startup in main.rs. If a parse or deserialization error occurs, the error is surfaced directly to the user, preventing the application from proceeding with invalid settings.

  3. Understand the Semantic Search Tool Selection Evaluation

    main

    The sem_search (Codebase Search) evaluation validates that the Forge agent correctly identifies and uses semantic search tools when presented with conceptual, functionality-based queries. This test ensures the agent distinguishes between semantic understanding (purpose/behavior) and regex-based exact pattern matching.

    Key Test Objectives

    • Correct Tool Invocation: Ensuring sem_search is called for conceptual queries.
    • Conceptual Recognition: Identifying queries that describe behavior rather than specific text strings.

    Target Use Cases for sem_search

    Use semantic search when queries involve:

    • Purpose/Behavior: e.g., "retry logic with exponential backoff"
    • Implementation Patterns: e.g., "authentication token validation"
    • Architectural Components: e.g., "message transformation between AI providers"
    • System Behaviors: e.g., "rate limiting for API requests"

  4. Migrate a Tool to a Service-Based Architecture

    main

    To migrate an existing tool (e.g., fs_read, shell, fetch) to the service-based architecture, follow this pattern established by the FSRead template:

    1. Implement the Service: Create a new service implementation in crates/forge_services/src/. The service should use Infrastructure traits and return anyhow::Result.
    2. Integrate into Services Trait: Add the new service to the main Services trait and implement it within the ForgeServices struct.
    3. Refactor the Tool: Convert the tool into a thin wrapper. The tool should receive the Services trait via dependency injection, retain ToolCallContext for UI/UX, and call the corresponding service method for its core logic.
    4. Update Tool Registry: Modify the tool registration process to inject the Services trait instead of raw Infrastructure.
    5. Migrate Tests: Move business logic tests from the tool implementation to the new service implementation. Keep UI and integration tests within the tool implementation.

  5. Use project-local agents via the .forge/agents/ directory

    main

    Forge supports loading agents from a project-local directory to complement your global agent collection. You can define project-specific agents by placing markdown (*.md) files in a .forge/agents/ directory located at the root of your current working directory (CWD).

    Agent Precedence Order

    If multiple agents share the same ID, Forge resolves conflicts using the following precedence (later sources override earlier ones):

    1. CWD Custom Agents: .forge/agents/ (Highest precedence)
    2. Global Custom Agents: {HOME}/forge/agents/
    3. Built-in Agents: Embedded in the Forge binary (Lowest precedence)

  7. Select a model using the `/model` command

    main

    You can change the active model for your project using the /model command in the Forge CLI. This command fetches available models from the API and provides an interactive selection interface. Once a model is selected, Forge updates the standard_model anchor in your project's forge.yaml file.

    If the forge.yaml file does not exist or the standard_model anchor is missing, the command will attempt to create or update them accordingly.

    /model

  8. Manage workspace auto-sync behavior

    main

    Forge uses a background sync mechanism via the ZSH plugin to keep workspaces updated. To prevent unintended workspace registrations in subdirectories, Forge follows these rules:

    1. Auto-sync is restricted to existing workspaces: The background sync will only trigger if the current directory or one of its ancestors is already registered as a workspace.
    2. Manual registration required for new workspaces: If you enter a new directory that you want to be a workspace, you must manually run forge workspace sync to register it. Once registered, it will auto-sync on future visits.
    3. Disable auto-sync: You can disable the background sync behavior by setting the FORGE_SYNC_ENABLED environment variable to false.

  9. Migrate from SessionConfig to ModelConfig

    main

    Due to the separation of domain and configuration, the Environment.session field (which was an Option<SessionConfig>) has been removed. Configuration related to sessions is now handled via ForgeConfig.session, which uses the Option<ModelConfig> type.

    When migrating code that previously destructured SessionConfig, ensure you update the field names to match the new ModelConfig structure.

  10. Configure a custom history file via FORGE_HISTORY_FILE

    main

    You can maintain separate prompt histories for different projects by setting the FORGE_HISTORY_FILE environment variable. This allows you to override the default global history file with a project-specific one.

    Path Resolution Rules

    • Relative Paths: If you provide a relative path (e.g., ./project-history), it is resolved relative to your current working directory where Forge is invoked.
    • Absolute Paths: If you provide an absolute path, it is used directly.
    • Default Behavior: If the FORGE_HISTORY_FILE variable is unset, Forge continues to use the default global history file (.forge_history).

    Platform Support

    • Unix/Linux/macOS: Supports standard Unix-style absolute and relative paths.
    • Windows: Supports drive letters (C:\path\to\history), UNC network paths (\\server\share\history), and both forward (/) and backslash (\) separators.
    # Unix/Linux/macOS examples
FORGE_HISTORY_FILE=./project-history
FORGE_HISTORY_FILE=../shared/team-history
FORGE_HISTORY_FILE=/home/user/forge-histories/project1

# Windows examples
FORGE_HISTORY_FILE=.\project-history
FORGE_HISTORY_FILE=..\shared\team-history
FORGE_HISTORY_FILE=C:\Users\Name\ForgeHistories\project1
FORGE_HISTORY_FILE=\\server\share\team-histories\project1

  12. Use the `execute-plan` skill for structured task execution

    main

    The execute-plan skill is used to execute structured task plans from markdown files with automatic status tracking. This skill is triggered when a user provides a plan file path in the format plans/{current-date}-{task-name}-{version}.md or explicitly requests the execution of a plan file.

    To use this skill, ensure your plan file uses the supported task status indicators to track progress.

    [ ]: PENDING
[~]: IN_PROGRESS
[x]: DONE
[!]: FAILED