Coding Agent Plugin: Manage Your Architecture Without Leaving Your Terminal

Last month, I watched a developer on our team do something that felt like it shouldn't work.

He was knee-deep in a refactoring session in Claude Code, splitting a monolithic service into three smaller ones. Halfway through, he typed: "Create three new containers in Archyl — OrderService, InventoryService, and NotificationService — under the ECommerce system. Add 'calls' relationships between OrderService and the other two."

Ten seconds later, the C4 model in Archyl had three new containers, correctly wired with relationships, sitting exactly where they should be in the architecture. He never switched tabs. He never opened a browser. He just kept coding.

That's when I realized the plugin was ready to ship.

The Context Switch Problem

Architecture documentation has a fundamental UX problem: it lives in a different place than the code.

You're in your IDE. You've just restructured a module, renamed three services, and split a database into read and write replicas. The code is done. Now you need to update the architecture. That means opening Archyl in a browser, finding the right project, navigating to the right diagram, updating the containers, adding relationships, maybe writing an ADR to explain why you made the change.

It takes five minutes. But those five minutes have a hidden cost: context switching. Your brain has to leave the code, enter a visual diagramming mode, remember what you just did, translate it into architecture concepts, and then go back to coding. Most developers just... don't. They tell themselves they'll update the documentation later. Later never comes.

This is why architecture drift exists. Not because teams don't care about documentation, but because the tool is in the wrong place at the wrong time.

Architecture in Your Conversation

The Archyl Developer Plugin puts your entire architecture inside your coding agent's context. It's a plugin for Claude Code (and compatible with Codex and other agents) that teaches the agent how to use all 200+ of Archyl's MCP tools.

What does that mean in practice? It means you can do this:

While refactoring, tell your agent to update the architecture:

I just split the PaymentService into PaymentProcessor and PaymentGateway.
Update the architecture — remove the old container, create the two new ones,
and move all existing relationships to the appropriate new container.

While reviewing code, ask about architectural context:

Get the full C4 model and tell me which components depend on the UserRepository.
Are there any conformance rules I should know about before changing the data layer?

While planning work, check if the documentation is still accurate:

What's the current drift score? Show me which elements have drifted
and what the AI thinks is out of date.

After a design meeting, record the decision without leaving your terminal:

Create an ADR: we decided to migrate from REST to gRPC for all internal
service communication. Context: latency requirements from the mobile team.
Link it to the ApiGateway and all backend service containers.

The agent handles the MCP calls, manages project IDs, and chains operations together. You just describe what you want in plain language.

What the Plugin Covers

The plugin gives your agent structured knowledge across seven domains:

C4 Modeling — Create and manage systems, containers, components, code elements, and relationships. The agent understands the C4 hierarchy and enforces proper naming conventions (PascalCase for systems and containers, exact symbol names for code elements).

Documentation — Write ADRs, create project docs, define user flows, and review AI-generated insights. ADRs are linked to the C4 elements they affect, so architectural decisions stay connected to the architecture.

Governance — Create conformance rules, run compliance checks, and monitor architecture drift. The agent can set up guardrails before an AI coding session even starts.

Operations — Track releases across environments, document API contracts (OpenAPI, gRPC, GraphQL), map event channels (Kafka, NATS, SQS), and manage the technology radar.

Collaboration — Add comments, create change requests (like PRs for architecture), and manage whiteboards. Architecture discussions happen where the code discussions happen.

History — Take snapshots, time-travel through architecture versions, and diff changes. When someone asks "what did the architecture look like before the migration?", the agent can answer.

Integrations — Configure webhooks for architecture change notifications, manage marketplace widgets, and view the global architecture across all projects in the organization.

Three Steps to Set Up

The setup is straightforward:

1. Add the marketplace and install the plugin:

/plugin marketplace add archyl-com/agent-skills
/plugin install archyl-developer@archyl-com-agent-skills

2. Add the MCP server to your project's .mcp.json:

{
    "mcpServers": {
        "archyl": {
            "type": "http",
            "url": "https://api.archyl.com/mcp",
            "headers": {
                "X-API-Key": "arch_your_api_key_here"
            }
        }
    }
}

3. Restart your agent and start talking to your architecture.

That's it. The plugin loads automatically and the agent knows how to use every tool. No configuration files, no custom prompts, no manual wiring.

Why Open Source

The plugin is fully open source at github.com/archyl-com/agent-skills. There are a few reasons for this.

First, transparency. When a plugin teaches an AI agent how to interact with your architecture, you should be able to read every instruction it gives. The skill definition, the reference files, the workflow examples — it's all there, in plain markdown.

Second, contributions. Archyl has over 200 MCP tools, and the best workflows emerge from real usage. When a team discovers a pattern that works — say, a workflow for auditing architecture before a major release — they can contribute it back. The plugin gets better because the community uses it.

Third, portability. The skill content isn't locked to Claude Code. It works with any agent that supports the plugin format. The .claude-plugin and .codex-plugin manifests are both included. If a new coding agent emerges next month with plugin support, the skill content transfers directly.

What Changes

The shift is subtle but significant.

Before the plugin, architecture documentation was a separate activity. You wrote code, then documented. Two workflows, two tools, two mental modes. Documentation was always a step behind because it was always a step away.

With the plugin, architecture documentation becomes part of the coding conversation. You don't "update the docs" — you mention what changed and the agent handles it. The architecture stays in sync not because someone remembered to update it, but because updating it became effortless.

This is especially powerful in agentic workflows. When an AI agent is making changes to your codebase, it can simultaneously update the architecture. The same session that refactors the code also updates the C4 model, records the ADR, and runs a conformance check. Architecture governance becomes a natural part of the development flow, not an afterthought.

Get Started

Install the plugin, connect your MCP server, and try asking your agent to describe your architecture. Then ask it to make a change. The first time you update a C4 model from a terminal conversation, you'll wonder why it ever worked any other way.

The plugin is available now. Full documentation is in our guides, and the source is on GitHub.

Your architecture shouldn't live in a different tab. Now it doesn't have to.