archwhere

archwhere serves as a comprehensive mission control system for AI coding agents, allowing developers to gain insightful oversight of their active pull requests (PRs) and associated tasks. By situating every change directly on a declared architecture map, it enhances the administrative efficiency of an agent workforce that may be processing as many as thirty PRs a week.

Key Features

• Architecture Maps: Visualize every PR and task on a detailed architecture map that displays which components are affected, their security statuses, and immediate needs. This allows for a clear understanding of the impact of changes in the code base.

• Agent Interactions: Communicate effectively with coding agents using the architecture map as a conversation surface. By pinning threads to components, teams can track discussions, PR statuses, and decisions directly within the context of the architecture.

• Automated Model Maintenance: Unlike traditional architecture tools, archwhere flips the paradigm by allowing agents to maintain the architecture map as a prerequisite for merging. The integration of a SKILL.md file instructs agents on how to contribute, while archwhere check serves as a continuous integration guard ensuring the model remains up-to-date. This innovation bypasses issues of decay inherent in models that require human oversight.

Getting Started

Getting started with archwhere is straightforward. The tool initializes with a command that generates the architecture model directly from the repository’s structure:

npx archwhere init

This rapidly constructs a draft model based on the repository, including guessed relationships and a comment workflow for PRs, simplifying the onboarding process.

Daily Commands

Several commands streamline workflow for developers:

npx archwhere                    # Determine what components are touched by the working tree.
npx archwhere --base origin/main # Assess impact of the current branch.
npx archwhere check              # Validate model integrity with a CI guard.
npx archwhere check --fix        # Automatically adopts unmapped files.
npx archwhere heat               # Identify components with the highest churn in the last 30 days.
npx archwhere doc --out ARCHITECTURE.md
npx archwhere mission            # Launch the interactive UI at http://localhost:4610

Intelligent PR Mapping

Each PR automatically receives a comprehensive comment that includes a summary of affected components and their statuses, highlighting security flags and providing a visual representation of component interactions:

flowchart LR
  web-app --> ticket-engine
  web-app --> auth
  ...

This enables immediate identification of dependencies and potential security risks. Additionally, if a PR introduces files that are not mapped, the tool intelligently suggests a fix, allowing the team to maintain an accurate and up-to-date architectural model effortlessly.

Enhanced Monitoring and Decision-Making

• Attention Rail: The architecture map features an attention rail that prioritizes security issues, pending decisions, and PRs that require urgency, facilitating quicker responses.
• Dynamic Analysis: Monitoring tools allow visualization from different perspectives, presenting insights into structural changes, recent activities, and runtime health based on defined metrics.

Bring Your Own Agent

archwhere integrates seamlessly with any coding agent, ensuring flexibility within operational frameworks. Typical configurations enable direct communication installations with agents like Claude or any other API-compatible agent.

Conclusion

archwhere revolutionizes the management of architectural oversight in software development, especially in environments governed by AI coding agents. With its user-friendly interface and intelligent mapping features, developers can focus on what truly matters — delivering quality code while maintaining architectural integrity.