BalloonTopic Drift Guard

Switch features without losing context—or trusting stale AI memory.

Comment

Inspiration

I did not start BalloonTopic as a hackathon idea. I created it because I needed it at work.

I regularly work across multiple company projects, repositories, and features at the same time. I might be implementing a backend feature, move to a frontend change, get interrupted by a production issue, and then return to the original feature a day later.

Git remembered my branches, but Cursor and Codex did not remember the work item in the same way. I kept opening different chats and repeating the same context: what I was building, which files mattered, what was already finished, which decisions we had made, and what still needed to be done.

Sometimes reconstructing the context took longer than the next small code change. More importantly, I was beginning to rely on AI-generated code without having a simple place to preserve the architectural decisions I still needed to understand myself.

That frustration became the first version of BalloonTopic, which I originally used as a Cursor skill. Each feature became a small local topic connected to its branch, progress, TODOs, important files, deployment notes, and PR.

While preparing BalloonTopic for OpenAI Build Week, I noticed that remembering old context was only half of the problem. The repository could change while I was working somewhere else. A shared model, API contract, migration, or configuration could make the saved context incorrect.

That became Drift Guard: feature memory that does not only remember where I stopped, but checks whether what it remembers is still true.

What it does

BalloonTopic Drift Guard gives each active feature a small, local memory that can be read by Cursor, Codex, Claude Code, or another coding agent. It is not a replacement for Git or a new project-management platform. It is the missing context layer between a Git branch and an AI conversation.

bt capture examines the active topic and bounded Git evidence. GPT-5.6 creates a structured context capsule containing:

  • Completed work and next actions
  • Decisions and assumptions
  • Key and risky files
  • Shared infrastructure
  • Verification commands
  • Details that require human understanding

bt resume` compares the saved feature and base-branch SHAs with current Git history. GPT-5.6 explains whether the context is still safe, needs review, or should be blocked. Every drift finding must cite an exact changed file or commit from the supplied evidence.

bt explain creates a feature-scoped architecture briefing covering data flow, system boundaries, failure modes, human-owned decisions, and the few files worth reading. It intentionally avoids producing a generic repository summary.

The goal is not to make developers read every line written by an AI. The goal is to make sure they do not miss the parts they are still responsible for understanding.

Example

A developer captures a payment-retry feature that depends on shared/user_schema.py, then switches to another task. While the payment feature is paused, main migrates User IDs from integers to UUIDs.

When the developer resumes payment-retry, Drift Guard reports:

> BLOCKED — A saved feature dependency changed: shared/user_schema.py

It then explains why payment jobs depend on that contract and recommends reviewing the schema before the AI continues.

How we built it

I kept the implementation intentionally small because I wanted something I could actually continue using after the hackathon.

Drift Guard is a local-first Python CLI backed by Git and local JSON topic files. It records both the feature HEAD and base-branch SHA, then calculates file and commit changes when the feature resumes.

For live analysis, it calls GPT-5.6 through the OpenAI Responses API. Each task uses a strict JSON schema so the capsule, drift report, and architecture briefing remain predictable and testable.

The prompts constrain GPT-5.6 to the available Git evidence and prohibit unsupported file paths. Diff input is bounded and truncated before transmission. API keys are read only from the environment.

The project has no backend, account system, hosted database, or cloud storage. Topic data stays in .balloontopic/, which is gitignored by default.

I also added a deterministic offline demo. It creates a temporary repository, captures a payment feature, changes a shared User ID contract on main, and then shows Drift Guard blocking the stale payment context. This lets anyone test the central idea without creating an account or supplying an API key.

How Codex was used

I built the original BalloonTopic workflow for Cursor before Build Week. For this extension, Codex became the main place where I scoped, implemented, tested, documented, and shipped Drift Guard.

I used Codex to:

  • Preserve the existing project as the v0.2.0 pre-event release
  • Scope Drift Guard to three commands rather than a large project-management app
  • Design the feature/base SHA comparison model
  • Implement the standard-library Python CLI
  • Create strict GPT-5.6 Structured Output schemas
  • Write and debug the cross-branch unit tests
  • Build and review the responsive product page
  • Prepare the judge demo, documentation, GitHub PR, and Vercel deployment

One useful part of building this with Codex was that the development process itself reproduced the problem BalloonTopic solves. The task accumulated product decisions, implementation details, test failures, deployment information, and submission requirements. Preserving that context mattered.

The main Build Week implementation was completed in one Codex task. I shared that task through /feedback, and its Session ID is included in the submission.

Challenges we ran into

My first assumption was that I could detect drift by comparing the current feature branch with the commit captured when it was paused. That was not enough.

The most important changes often happen somewhere else. A feature branch may remain completely unchanged while its base branch changes a shared database model, API response, environment variable, or deployment rule.

We solved this by capturing two boundaries: the feature HEAD and the base-branch SHA. On resume, Drift Guard compares both boundaries with current Git refs and provides the resulting evidence to GPT-5.6.

Another challenge was making the product useful without encouraging developers to trust another AI summary blindly. The final design treats Git as evidence and the capsule only as an explanation layer.

I also wanted the project to remain practical. It would have been easy to turn it into a hosted dashboard with accounts, synchronization, and another database. That would have moved it away from the original problem. BalloonTopic remains a small set of files beside the code, readable by both humans and agents.

Accomplishments that we're proud of

The result is a tool I can genuinely use in the same company workflow that inspired it.

I am especially happy that it:

  • Detects base-branch drift even when the feature branch has not changed
  • Produces structured GPT-5.6 reports grounded in Git evidence
  • Keeps feature data local and portable across different coding agents
  • Surfaces the decisions a developer should understand instead of hiding them
  • Provides a complete offline demo with no API key or build step
  • Clearly separates the original Cursor version from the Build Week extension
  • Includes tests for capture, drift detection, architecture scope, and API shape

What we learned

I started with the idea that AI coding tools needed better memory. I finished with a slightly different conclusion: memory by itself can be dangerous.

Useful development memory must be tied to versions, grounded in evidence, and able to admit when it has become stale.

AI-assisted developers do not need to read every generated line, but they do need visibility into shared contracts, migrations, security boundaries, deployment assumptions, and other decisions that remain human-owned.

I also learned that the best tool for my workflow was not the biggest one. A small JSON file, a few Git boundaries, and a focused AI explanation can be more useful than another large dashboard.

What's next for BalloonTopic Drift Guard

My next goal is to use Drift Guard in my real multi-project workflow and improve it from actual interruptions rather than imagined use cases.

The next additions I want to explore are:

  • Dependency-level drift beyond direct file overlap
  • Better native installation for Codex, Cursor, and Claude Code
  • Multi-repository topics for features spanning frontend and backend projects
  • Verified PR handoff summaries
  • Team-defined rules for changes that always require human review

Testing instructions for judges

No credentials are required.

Fastest path

  1. Visit https://balloontopic-drift-guard.vercel.app
  2. Use the Capture, Shared change, and Resume tabs in the interactive demo.

Complete runnable demo

git clone https://github.com/radhakishan404/balloontopic.git
cd balloontopic
python3 scripts/run_demo.py

Expected result: the demo captures a payment feature, changes the shared User ID contract on main, then returns a BLOCKED drift report citing shared/user_schema.py.

Automated tests

python3 -m unittest discover -s tests -v

Live GPT-5.6 analysis

export OPENAI_API_KEY="your-key"
bash scripts/bt.sh capture
bash scripts/bt.sh resume
bash scripts/bt.sh explain

Developer-tool installation and platforms

Supported platforms

  • macOS
  • Linux
  • Windows through WSL or Git Bash

Requirements

  • Git
  • Bash
  • Python 3

Install as a Cursor skill

git clone https://github.com/radhakishan404/balloontopic.git
ln -s "$(pwd)/balloontopic" ~/.cursor/skills/balloontopic

The same SKILL.md can be referenced by Codex or Claude Code. Detailed instructions are available in the repository README.

Built With

Share this project:

Updates

Submission history