Architecture audit tool - OpenSRE Documentation

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

opensre integrations setup github
opensre integrations verify github

Typical workflow:

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

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

> 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 (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}/…

Investigation 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

Related skill: architecture-audit.

`architecture_clone_repo`

{
  "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.

{
  "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

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, GitHub workflow tools, Shell commands.

​Overview

​Prerequisites

​Setup

​Credentials

​Investigation tools

​architecture_clone_repo

​architecture_save_observations

​Gotchas

​Verify

​Troubleshooting

​Security