> ## Documentation Index
> Fetch the complete documentation index at: https://opensre.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture audit tool

> Clone a GitHub repo, run architecture shell passes, and persist full audit observations from the interactive shell

OpenSRE provides GitHub-backed **architecture audit** tools for reviewing repository structure — import boundaries, file placement, size limits, and shim patterns. Use them from the interactive shell (`opensre`) when you want a structured architecture review before or alongside an incident investigation.

## Prerequisites

* GitHub connected via [GitHub integration](/docs/github) **or** a token in `GITHUB_TOKEN` / `GH_TOKEN`
* For private repos, ensure the token has `repo` read scope

## Typical workflow

1. **Clone** the target repository into a fixed temp workspace
2. Run architecture **shell heuristic passes** (import, placement, size, shim) via the action agent
3. **Save** the full untruncated observation list to disk
4. **Cleanup** the clone when finished

In the REPL, describe what you want in plain language:

```text theme={null}
> clone Tracer-Cloud/opensre and run an architecture audit on it
```

Or invoke tools explicitly through the action agent.

## Tools

| Tool                             | What it does                                                                                     | Side effects          |
| -------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------- |
| `architecture_clone_repo`        | Shallow-clone `owner/repo` into `opensre/workspace` under the system temp directory              | Creates files on disk |
| `architecture_cleanup_repo`      | Delete the architecture workspace (refuses paths outside the allowed directory)                  | Deletes clone         |
| `architecture_save_observations` | Write the full observation list to `~/.opensre/{session_id}/{repo}-architecture-audit-{uuid}.md` | Writes a file         |

### `architecture_clone_repo`

```json theme={null}
{
  "owner": "Tracer-Cloud",
  "repo": "opensre",
  "ref": "main"
}
```

Returns `workspace_root` — the path to the clone. Always call `architecture_cleanup_repo` when finished.

### `architecture_save_observations`

Call **after** cleanup and **before** the final summarized report. Pass the **complete** findings from all four shell passes (import, placement, size, shim) — not the short user-facing summary.

```json theme={null}
{
  "repo_name": "opensre",
  "observations": "## Import pass\n- ...\n## Placement pass\n- ..."
}
```

## Verify GitHub access

```bash theme={null}
opensre integrations verify github
```

Expected output includes MCP tool discovery; architecture tools additionally accept `GITHUB_TOKEN` when GitHub MCP is not configured.

## Gotchas

* **Always cleanup.** `architecture_clone_repo` leaves a shallow clone on disk until `architecture_cleanup_repo` runs. The tool description enforces this workflow.
* **Workspace is fixed.** Clones go under the architecture workspace in the system temp directory — you cannot point the clone at an arbitrary path.
* **Save the full list.** `architecture_save_observations` expects untruncated pass output. Saving only the short report template loses audit evidence.
* **Session id required.** Saving observations needs an active interactive-shell session (`~/.opensre/sessions/`). Start `opensre` before running the audit.

## Related docs

* [GitHub](/docs/github) — token scopes and MCP setup
* [GitHub workflow tools](/docs/github-workflow-tools) — engineering digests and PR status (separate from architecture audit)
* [Interactive Shell Commands](/docs/interactive-shell-commands) — slash commands and session management