> ## 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

## Overview

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/integrations/code/github) **or** a token in `GITHUB_TOKEN` / `GH_TOKEN`
* For private repos, ensure the token has `repo` read scope
* An active interactive-shell session when saving observations

## Setup

There is no dedicated integration setup. Connect GitHub, then use the tools from the REPL.

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

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.

## Credentials

Uses the same GitHub credentials as [GitHub](/docs/integrations/code/github) (`GITHUB_MCP_AUTH_TOKEN`, browser sign-in, or `GITHUB_TOKEN` / `GH_TOKEN`). Architecture tools additionally accept `GITHUB_TOKEN` when GitHub MCP is not configured.

* Clones land under the architecture workspace in the system temp directory (`opensre/workspace`)
* Saved reports go under `~/.opensre/{session_id}/…`

## 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- ..."
}
```

### 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.

## Verify

```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. There is no separate architecture-audit verify target.

## Troubleshooting

| Symptom                        | Fix                                                                          |
| ------------------------------ | ---------------------------------------------------------------------------- |
| **Clone fails / auth**         | Verify GitHub credentials and `repo` scope for private repos                 |
| **Save fails without session** | Start `opensre` so a session id exists under `~/.opensre/sessions/`          |
| **Leftover clone on disk**     | Run `architecture_cleanup_repo`                                              |
| **Short report only**          | Pass the full four-pass observation list to `architecture_save_observations` |

## Security

* Prefer a read-only GitHub token scoped to the repos you audit.
* Always clean up clones when finished.
* Related: [GitHub](/docs/integrations/code/github), [GitHub workflow tools](/docs/integrations/code/github-workflow-tools), [Shell commands](/docs/getting-started/interactive-shell-commands).