> ## 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](https://opensre.com/docs/integrations/code/github.md) in the OpenSRE app
* 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 authorized app connection from the [GitHub integration](https://opensre.com/docs/integrations/code/github.md).

* Each audit clones into its own directory 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 clone at the `workspace_root` that `architecture_clone_repo` returned in the same session (refuses any other path) | 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 this audit's clone. Always pass it to `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. Clones left behind for more than a day are removed when the next audit starts.
* **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 require an authorized app connection. 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` with the clone's `workspace_root` in the session that cloned it. Clones left by another session or an earlier run are removed automatically after 24 hours. |
| **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](https://opensre.com/docs/integrations/code/github.md), [GitHub workflow tools](https://opensre.com/docs/integrations/code/github-workflow-tools.md), [Shell commands](https://opensre.com/docs/getting-started/interactive-shell-commands.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.