CAP Is Deprecated

To learn more, keep reading.

CAP - What Was It, What It Wasn’t, and What I Learned

I always thought I had a good understanding of what the world needs, and this time I was right. Just as the world was approaching the peak of AI usage in terms of usability, I always felt like lacking a way to pass my codebase information to AI agents. After seeing how useful MCP servers could be, I thought of a way to define codebase’s structure by writing a simple YAML file with SoC principles listed.

I decided to call this tool the Codebase Awareness Protocol.

Why I Thought It Was a Good Idea

On paper, the idea was great: everything the AI needs to continue building a project fit into a single YAML file. The AI would then be able to read the file and understand the structure of the codebase, allowing it to make informed decisions about how to proceed with development.

Until then, I had to manually tell it what to read, how to code, and more. Maybe a part of this was my want of keeping the codebase traceless, while the rest of the world was more forgiving to how others’ code was structured. I thought that if I could make a tool that would allow AI to understand the structure of a codebase, it would be a game-changer for developers.

It was for me, but it wasn’t very convenient. Clamping down a codebase into the tight struture of a CAP-compatible YAML file was a lot of work, even if it was very flexible.

(Probably) Why It Failed

CAP’s idea was at the right place, at the wrong time. It reminds me of Blackberry and their keyboards. Idea - brilliant, but bigger screen that could ALSO have a keyboard was more convenient.

Another major point of failure was that at the time, I was practically invisible, and have shown the project only to a handful of people. The bigger of a player you are, the more likely your project is to be adopted.

The last aspect was that the VSCode extension I built wasn’t very user-friendly and would often crash trying to reach a mismatched Python version. I didn’t have much enjoyment building and deploying the extension, so I stopped maintaining CAP myself. It didn’t help that custom MCP servers had to be user-approved in deeply stacked VSCode menus, which didn’t add to the convenience for developers. Shortly after I moved to using Skills myself.

Development Perspective

From a strict development viewpoint, the project was structured nicely, and, most importantly, worked reliably, if using standalone through CLI. The file architecture was defined as follows:

cap/
├── core/                   # cap-core - parsing, validation, formatting
│   └── cap_core/
│       ├── domain/         # Pydantic models - pure data, no I/O
│       │   └── models/
│       ├── infrastructure/ # FileReader - the only class that touches disk
│       └── application/    # ConfigService, ValidationService, MCPFormatter
│           └── services/
├── mcp/                    # cap-mcp - FastMCP server with stdio transport
│   └── cap_mcp/
│       ├── server.py       # Composition root - wires ConfigService into tools
│       └── tools/          # One file per MCP tool
├── shells/
│   ├── cli/                # cap-cli - click-based CLI
│   │   └── cap_cli/
│   │       ├── commands/   # init, serve, validate
│   │       ├── templates/  # Default .cap/ YAML files
│   │       └── utils/      # Workspace detection, output helpers
│   └── vscode/             # VS Code extension - TypeScript
│       └── src/
│           ├── setup/      # Python discovery, venv management, updates
│           ├── cap/        # CLI runner, init commands, validation
│           ├── mcp/        # MCP server provider, enable notice
│           └── utils/      # Shared workspace/venv/watcher helpers
└── .cap/                   # CAP's own configuration (we eat our own dogfood)

I even had big plans for versioning and how to report CAP format updates back to the developer, CLI command set was easy to use, default files that CAP provisioned also included a very rich, but minimal config file set that, if creating a project from zero, was easy to maintain. Problem was that scaling CAP with big codebases was kind of a pain.

Design decisions of CAP’s internals were also simple, but effective. It used:

• Pydantic models
• Deduplication principles
• Separation of MCP tools
• Subprocessing the extension and native multiple-shell support
• Auto-formatting of code and quick file validation

It was built with cuting-edge technology back then too. I like the decisions I have made developing CAP, its modularity, and I’m still following the same patterns in my newer projects till this day. I think that after all, the project was a success in terms of development.

Conclusion

In conclusion, the CAP project was a crucial learning experience that taught me a lot about software architecture and design principles. While it may not have achieved the widespread adoption I had visioned, the technical foundation and a workout to my worldview senses were extremely valuable as I continued my software development growth. Even if this means no longer maintaining this project.