How SWE-Agent Uses the workspace_repo Directory for Target Codebase Modifications

The SWE-Agent treats workspace_repo as the canonical root directory for all target codebase operations, using it as the base path for file discovery, search, and modification across its architect and developer graph nodes.

The workspace_repo directory serves as the isolated working environment where the SWE-Agent performs all inspection and mutation operations on target repositories. In the langtalks/swe-agent codebase, this folder acts as the single source of truth for the agent's tools and LangGraph workflows, ensuring every file read and write operation is scoped to the intended project.

Core Tools That Interface with workspace_repo

The agent's tool layer in agent/tools/ explicitly references workspace_repo as the default working directory. These utilities form the bridge between the LLM reasoning engine and the filesystem.

File Structure Discovery via get_files_structure

The get_files_structure function generates a JSON representation of the entire repository tree, enabling the LLM to reason about file organization before making changes. Located in agent/tools/write.py:54-66, this tool calls gitingest.ingest on the supplied directory (defaulting to "./workspace_repo") and returns a hierarchical mapping of files and directories.

# Example: Retrieve the complete file tree of the target repo

tree = get_files_structure.invoke({"directory": "./workspace_repo"})
print(tree)   

# → {"src": {"main.py": "...", "utils.py": "..."}, "tests": {...}}

Codebase Search with search_keyword_in_directory

The search_keyword_in_directory tool, implemented in agent/tools/search.py:98-99, resolves user-provided paths to absolute paths via get_full_path and executes keyword searches within the workspace_repo boundary. This allows the research phase to locate specific APIs, function definitions, or configuration patterns across the target codebase.

# Example: Search for database-related code within the workspace

result = search_keyword_in_directory.invoke({
    "directory": "./workspace_repo",
    "search_term": "database",
    "context": 2,
})
print(result)   

# → list of matching files with surrounding context lines

File Creation and Modification Operations

The write tools in agent/tools/write.py:7-27 and 31-49 handle all mutations to the target codebase. Both create_file and write_to_file accept paths relative to the repository root, automatically ensuring parent directories exist before persisting changes. These operations are constrained to paths within workspace_repo to prevent accidental modifications to the agent's own source code.

# Example: Create a new module within the workspace

create_file.invoke({
    "path": "./workspace_repo/new_module/helper.py",
    "content": "def hello():\n    return 'world'",
})

# Example: Patch an existing file after generating a diff

write_to_file.invoke({
    "path": "./workspace_repo/app/models.py",
    "content": edited_code,
})

Graph-Based Orchestration of workspace_repo Operations

The agent's LangGraph architecture relies on workspace_repo as the shared context for both planning and implementation phases. Each graph node explicitly passes the directory path to maintain filesystem isolation.

Architect Graph: Planning with Repository Context

During the research and planning phase, the architect graph repeatedly invokes get_files_structure with directory="./workspace_repo" to ground the LLM's reasoning in the actual file layout. According to the source in agent/architect/graph.py:51-55, 84-85, 108-109, and 131-132, every planning step requests the current codebase structure before extracting an ImplementationPlan. This ensures the architect agent understands the existing architecture before proposing modifications.

Developer Graph: Implementing Targeted Changes

The developer graph handles the execution of file modifications, reading target files directly from workspace_repo and writing diffs back to the same location. As implemented in agent/developer/graph.py:98-100, the developer node reads file contents from paths like ./workspace_repo/app/models.py, generates code changes via LLM prompting, and persists results using the write tools. This graph also fetches the repository tree via get_files_structure("./workspace_repo") to validate file existence before operations.

The Complete workspace_repo Workflow

The SWE-Agent orchestrates target codebase modifications through a five-phase workflow that treats workspace_repo as the immutable boundary for all operations:

1. Bootstrap – The target repository is cloned or copied into the workspace_repo directory, isolated from the agent's installation files.
2. Discovery – get_files_structure builds a JSON representation of the tree at agent/tools/write.py:54-66, providing the architect and developer agents with a complete map of available files.
3. Search & Research – The search tool scans files under workspace_repo for keywords and API usage, feeding results back to the research loop at agent/tools/search.py:98-99.
4. Planning – The architect extracts an ImplementationPlan based on the repository structure and research findings, referencing the tree data from agent/architect/graph.py.
5. Implementation – The developer graph reads target files from workspace_repo, generates diffs, and writes changes back via the tools defined in agent/tools/write.py.

Summary

• workspace_repo acts as the root filesystem boundary for all SWE-Agent operations, preventing modifications to the agent's own codebase.
• The file structure tool (agent/tools/write.py:54-66) and search tool (agent/tools/search.py:98-99) both default to ./workspace_repo when resolving paths.
• The architect graph uses repository structure data from workspace_repo to generate implementation plans grounded in actual file layouts.
• The developer graph performs read-modify-write cycles exclusively within workspace_repo, using relative paths that resolve to this directory.
• All write operations validate parent directory existence before persisting changes, ensuring robust file creation within the workspace boundary.

Frequently Asked Questions

What is the default path for workspace_repo in SWE-Agent?

The default path is "./workspace_repo", as specified in the get_files_structure tool signature and referenced throughout agent/tools/write.py. This relative path resolves to the agent's execution directory, serving as the isolated container for target repository clones.

How does the architect graph use workspace_repo during planning?

The architect graph invokes get_files_structure with directory="./workspace_repo" at multiple stages (lines 51-55, 84-85, 108-109, and 131-132 in agent/architect/graph.py) to retrieve the current codebase structure. This JSON tree is passed to the LLM to enable reasoning about existing file organization before generating implementation plans.

Can SWE-Agent create files outside of workspace_repo?

No. The write tools (create_file and write_to_file in agent/tools/write.py:7-27 and 31-49) accept paths relative to the repository root, and the developer graph constructs these paths specifically within ./workspace_repo. While the tools themselves could theoretically write to arbitrary paths, the graph implementation constrains operations to the workspace directory to maintain security and isolation.

How does the search tool handle path resolution within workspace_repo?

The search_keyword_in_directory tool in agent/tools/search.py:98-99 uses a get_full_path helper to resolve user-provided paths to absolute paths before executing searches. When no specific directory is provided, it defaults to searching within workspace_repo, ensuring all keyword searches remain scoped to the target codebase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}