Repoburg
Login

Core Workflows

This section covers the primary workflows you'll use within the Repoburg application, from managing sessions to interacting with the AI's plans and using shortcuts.

Session Management

A "session" in Repoburg is a complete conversation with the AI, including all your prompts and the AI's generated plans.

Starting a New Session

Click the New Session button in the Session Panel. A new, empty session will be created, inheriting the default system prompt and context templates.

Creating a Follow-up Session

When you have an existing session loaded, you can click the Follow-up button. This creates a new session with an initial context derived from the previous one. Specifically, it gathers all files that were created, edited, or explicitly mentioned in the previous session and adds them as ad-hoc context to the new session's first prompt. This is a powerful way to continue a complex task without losing context.

Session History

The Session History page (accessible from the home dashboard) lists all of your previous sessions.

  • Loading a Session: Simply click on a session title to load it into the active view. Its full conversation history and the final state of its plan will be displayed.
  • Filtering: You can choose to hide empty sessions (sessions where no prompts were ever sent).
  • Sorting: You can sort sessions by date, either newest or oldest first.

Import / Export

You can easily back up or share your sessions.

  • Export: From the Session History page, use the action menu (...) for any session and select Export. This will download a .json file containing the entire session, including all prompts, AI responses, and related entities like the templates that were used.
  • Import: Click the Import Session(s) button on the Session History page. You can select a previously exported .json file to import it into your database. The import process will skip any entities (sessions, templates, etc.) that already exist with the same ID, so it's safe to re-import a file.

Execution Strategies & Plan Interaction

You can choose an execution strategy for each prompt you send. This determines how AI-generated actions are handled and how you interact with them in the Plan Interaction view. The header of this view also provides quick navigation, including a shortcut to the Editor for easy context browsing.

Review First

This is the safest workflow.

  1. The AI proposes a plan of actions (e.g., create_file, edit_file, quick_edit).
  2. No changes are made to your file system yet.
  3. You review each proposed action. You must explicitly Accept Change for each action you agree with. You can also Discard Change.
  4. Once you've reviewed the plan, you click the global Apply Approved Changes button to execute only the actions you accepted.

Apply & Revert

This is a faster, more iterative workflow.

  1. The AI generates a plan of actions.
  2. The actions are immediately applied to your file system. The original content of any modified or deleted files is saved in memory.
  3. You review the changes. The status of each action is "applied_pending_review".
  4. For each action, you can either Keep Change (confirming it) or Revert Change (which undoes the modification).
  5. You can also use the global Confirm All or Revert All buttons.

The AI Action Block

Each action is displayed in its own collapsible block showing its type, target, status, and order. Expanding it reveals details like a code diff or command string, along with the action controls (Accept, Discard, Keep, Revert). The most common actions are:

  • create_file, edit_file, delete_file: Standard file operations, rendered as a diff.
  • quick_edit: A special tool for making small, targeted changes (like inserting a line or replacing a small block of text). This is also rendered as a diff. It's designed for precision and has a built-in self-correction mechanism (see below).
  • run_command: Shows the shell command the AI wants to run.
  • request_context: Shows the files and folders the AI is asking for.

Self-Correction with quick_edit

The quick_edit tool has a unique, powerful feature: self-correction. To perform its job, quick_edit requires that the search_block of code it's looking for is unique within the file.

  • If the edit fails because the block isn't found or appears multiple times, the tool doesn't just error out.
  • Instead, it automatically generates a detailed feedback message explaining the failure (e.g., "The search_block was not unique").
  • This feedback is sent back to the LLM, which then attempts the action again, but this time with a more specific and unique search_block. This creates a robust, closed loop that allows the AI to correct its own mistakes, increasing the success rate of its plans without requiring manual intervention from you.

Execution Logs

After an action is executed (either applied or reverted), logs of the operation will appear in a summary at the bottom of the page and within the individual action blocks. This helps you confirm what happened and diagnose any errors.

Orchestration Workflow

For complex, multi-step tasks that require sequential AI interactions, you can use Orchestrations to automate the entire process.

  1. Create a Script: From the "Orchestrations" page, create a script (.rc.md file) that defines a series of prompts for the AI, separated by $$$$.
  2. Start a Run: Select a script and an active session, then click "Run".
  3. Automated Execution: Repoburg takes over, executing each step defined in your script:
    • It sends the prompt to the LLM using a special auto_apply strategy.
    • It receives the AI's action plan and immediately applies the changes to your files.
    • It proceeds to the next step.
  4. Monitor: You can monitor the progress via the status banner in the Session Panel and the detailed logs in the Plan Interaction view.
  5. Completion: The run completes when all steps are successful, or it fails if any action cannot be applied.

Codebase Exploration & request_context

A powerful feature of Repoburg is its ability to interact with AI models that can gather information before acting. The AI can use several tools for this exploration: request_context to ask for file contents, run_command to execute shell commands, and use_mcp_tool to interact with external tools.

The Exploration Loop

When the AI determines it needs more information to fulfill your request, it will respond with one of its exploration actions instead of a plan to modify files. How Repoburg handles this depends on your settings.

Automated Mode (Default)

  • By default, Auto Context Fetch is enabled in the Workflow Settings.
  • When Repoburg receives a request_context action, it automatically:
    1. Validates that the requested files and folders exist.
    2. Adds them to the ad-hoc context.
    3. Re-runs your original prompt using your default follow-up template, now including the new context.
    4. Sends the newly generated, richer prompt to your external AI tool via WebSocket. The "AI Studio PowerTools" userscript will automatically paste this new prompt for you.
  • This creates a seamless, conversational loop where the AI explores the codebase with minimal manual intervention from you.

Manual Mode

  • If you disable Auto Context Fetch, the loop becomes manual.
  • When Repoburg receives a request_context action, it will:
    1. Display the action in the Plan Interaction view.
    2. Show you which files and folders the AI requested, and why.
    3. Automatically add the requested items to the ad-hoc context for your next prompt.
  • You can then review the requested items, add or remove context as you see fit, and re-submit your prompt when you are ready. This gives you full control over the exploration process.

Concluding the Exploration

Once the AI has gathered all the necessary context, it can conclude the exploration phase by issuing a final action. This action contains a final analysis, summary, or answer to your original query. The explanation is rendered as formatted markdown inside its own action block within the plan, providing a clear and formal conclusion to the exploration loop.

Manual LLM Mode (Using an External AI)

This mode allows you to use any external AI model (e.g., a private Llama instance, Claude, or a specific version of Gemini/GPT). With the AI Studio PowerTools userscript, this workflow is almost entirely automated.

  1. Enable Manual LLM in the global Settings page.
  2. Write your prompt in the Session Panel as usual and click the Send button.
  3. Repoburg generates the full context. If the userscript's WebSocket is connected, this context is automatically sent to AI Studio and pasted into the prompt box.
  4. The AI generates its response in the AI Studio interface.
  5. The userscript's Network Interceptor detects the new response, parses the entire conversation, and sends it back to your local Repoburg backend.
  6. Repoburg receives the sync, updates its session state to match, and processes the latest AI response to generate a plan, all without any manual copy-pasting.

The old workflow of manually copying from Repoburg to the LLM and back is still possible if the userscript is disabled, and hotkeys like Cmd/Ctrl + Shift + V can speed up the process.

Shortcuts & Command Palette

Command Palette

Press Cmd/Ctrl + Shift + P anywhere in the application to open the Command Palette. This gives you quick, searchable access to almost every action, including:

  • Navigating to different pages (like the Plan Interaction, Markdown Editor, or MCP Management pages).
  • Creating or editing templates, prompts, and snippets.
  • Loading recent sessions.

Keyboard Shortcuts

  • Cmd/Ctrl + P: Open the global file search palette.
  • Cmd/Ctrl + Shift + P: Open Command Palette.
  • Double-press Ctrl: Open the Repoburg Variables quick-toggle modal.
  • Cmd/Ctrl + Shift + V: Paste raw LLM output from clipboard to the active session.
  • Alt + R: Reload the active session from the backend.
  • Alt + Shift + N: Start a new session.
  • Cmd/Ctrl + Enter: (In prompt input boxes) Send the prompt or prepare the manual LLM input.
  • Cmd + B: Toggle the main sidebar (in supported views).