DOCSEARCHbyAlgolia
Submit Docs

Refact Documentation

repository·main·Indexed 25 days ago

https://github.com/smallcloudai/refact

An open-source, local-first AI coding assistant providing IDE chat, autonomous agent workflows, and tool-powered development. Includes documentation for the refact-lsp Rust engine, the refact-chat-js GUI, and plugins for JetBrains and VS Code.

Tokens
47.7K
Snippets
79
Records
355
Agent score
82%

What's inside Refact

  1. Overview of Refact Core Pillars

    main

    Refact is a local-first coding assistant designed to run on your machine. Its architecture is built on several key pillars:

    • Local Engine: The refact-lsp engine runs locally and communicates with your IDE via localhost. It manages chat sessions, tools, code completion, local indexes, trajectories, tasks, and knowledge.
    • IDE Chat & Agent Workflows: Provides chat for codebase questions and autonomous agent modes for multi-step edits, searches, and tests.
    • Code Completion: Supports fill-in-the-middle suggestions via completion-capable providers or local runtimes.
    • Providers & Local Runtimes: Supports Bring Your Own Key (BYOK) providers and local model runtimes.
    • Integrations: Extensible via tools like shell commands, Chrome, GitHub, GitLab, Docker, PostgreSQL, MySQL, PDB, and MCP.
    • Local Context & Knowledge: Project trajectories, knowledge, task boards, and usage summaries are stored locally. Data only leaves your machine to reach the providers or integrations you explicitly configure.

  4. Overview of Refact Agent capabilities

    main

    Refact Agent transforms chat into a multi-step autonomous development workflow. It is designed for complex tasks that require reasoning, tool usage, and multi-file coordination rather than simple code explanations.

    Key Capabilities:

    • Context Gathering: Inspects project trees, reads files, performs text/vector searches, and looks up AST symbols.
    • Code Manipulation: Creates/updates files, applies patches, moves/removes files, and performs undos.
    • Execution: Runs shell commands, tests, linters, and builds; manages background services.
    • Web Automation: Fetches web pages, searches the web, and automates Chrome (screenshots, DOM inspection, etc.).
    • Advanced Reasoning: Uses planning, code review, deep research, and subagents.
    • Workspace Management: Updates task boards, saves knowledge, and provides rollback via workspace checkpoints.

  5. Understand Refact data privacy and local-first architecture

    main
    Refact is designed as a local-first tool. It does not require a hosted Refact account, a Refact-issued API key, or a Refact-operated model relay to function. Most operational data is stored locally in user/project directories (such as .refact/ or local config/cache directories).

  6. Available Refact Agent integrations

    main

    Refact Agent supports several categories of integrations to extend its functionality beyond the local codebase:

    Built-in runtime tools

    • Chrome and browser automation: Access to browser tabs, screenshots, DOM inspection, element interaction, console logs, and page extraction.
    • Shell commands: Execution of one-off local commands with support for timeouts, output filtering, and confirmation rules.

    Version control and code hosting

    • GitHub: GitHub CLI operations (e.g., issues and pull requests).
    • GitLab: GitLab CLI operations (e.g., issues and merge requests).
    • Bitbucket: Bitbucket Cloud API operations for repositories and pull requests.

    Databases and debugging

    • PostgreSQL: Execution of a single psql query per tool call.
    • MySQL: Execution of a single mysql query per tool call.
    • PDB: Control over interactive Python debugger sessions.

    Custom tools and protocols

    • Command-line Tool: Expose a single blocking command with parameters filled by the model.
    • Command-line Service: Manage long-running processes (start, stop, restart, and check status).
    • MCP Server: Connect to local stdio or remote HTTP/SSE Model Context Protocol (MCP) servers.

  7. Understand how Refact Code Completion works

    main

    Refact code completion operates through a local engine within your IDE. The process follows these steps:

    1. The IDE transmits the active file content, current cursor position, and surrounding text to the local Refact engine.
    2. The engine constructs a 'fill-in-the-middle' completion request using the available local context.
    3. The request is sent to your configured completion provider or local runtime.
    4. The provider returns a suggestion, which the IDE displays inline for you to accept, edit, or ignore.

  8. Capabilities of the Bitbucket Integration tool

    main

    Once configured, the bitbucket tool allows the Refact Agent to perform several repository-focused operations, including:

    • Listing repositories within a workspace.
    • Listing pull requests for a specific repository.
    • Reading a specific pull request by its ID.
    • Creating a new pull request from a source branch to a destination branch.
    • Reading files from a repository at a specific commit or branch.

  9. Understand Refact local context sources

    main

    Refact builds project context locally on your machine to help models understand your code. The context is prepared locally and only sent to the selected provider or local runtime for specific requests.

    Sources of context include:

    • IDE State: Current file, cursor location, selected snippets, and open editors.
    • Project Structure: Project tree and file contents (subject to privacy settings).
    • AST Indexes: Symbol definitions, references, and file symbols.
    • Vector Indexes: Semantic search over code, markdown, and saved trajectories.
    • Git State: Git state, checkpoints, and patch previews (when agent workflows are enabled).
    • Chat & Metadata: Chat history, task metadata, saved knowledge, and previous trajectories.
    • Tool Results: Shell output, web pages, browser screenshots, database rows, and integration responses.

  10. Understand Hidden Message Roles: event and plan

    main

    Refact chat history includes hidden roles used for internal bookkeeping. These roles allow the agent to store facts and task states without cluttering the main user/assistant transcript. They are saved in trajectories and snapshots but are hidden from the normal chat flow.

    • event: Stores internal facts like tool decisions, mode switches, process completions, and system notices. These appear in the collapsible Event log in the GUI.
    • plan: Stores the agent's current and previous Markdown plans, including version metadata. These appear in the Plan banner pinned above the chat transcript.

  12. Understand Refact Agent GUI host modes

    main

    The host configuration determines how the GUI communicates with its environment:

    • web: Runs directly in a browser and communicates with refact-lsp via HTTP/SSE.
    • ide: A generic postMessage host mode designed for IDE containers.
    • vscode: Utilizes the VS Code webview bridge.
    • jetbrains: Utilizes the JetBrains webview bridge.