Vabana - Agent Expressions

Vabana solves a clear developer-experience problem: AI coding agents communicate their internal state through a floating visual layer rather than forcing users to continuously read terminal output.

Comment

Inspiration

AI coding agents perform many actions in the background: reading files, searching code, running commands, delegating work, requesting approval, and verifying results. Most of this activity remains inside the chat, so users must constantly watch the transcript to understand what is happening.

AI agents also lack a digital embodiment outside their interface. Vabana grew from my third-semester research into whether explaining an AI assistant’s actions could improve trust during complex tasks. Its name is inspired by the Nepali word for feelings or emotions, reflecting the goal of giving AI agents understandable visual body language.

The idea for Vabana grew from my third-semester project, where I studied whether explaining an AI assistant’s actions could improve trust in complex task environments. Vabana—whose name is inspired by the Nepali word for feelings or emotions—explores that idea through ambient digital body language for AI agents.

What it does

Vabana gives AI coding agents a floating visual presence on macOS.

It receives native lifecycle events from Codex and Claude Code and converts them into readable activity cues. Rather than showing every hook event, Vabana highlights meaningful moments such as thinking, using tools, requesting approval, delegating to a subagent, and completing a turn.

Native activity can appear in two styles:

  • Pulse shows brief emoji-based expressions for important transitions.
  • Card provides a persistent, compact view of the provider, current activity, tool, subagent, verification state, and supported provider-reported usage information.

Vabana also provides MCP tools for intentional agent expression. Agents can display moods, emojis, GIFs, messages, prompts, code, diffs, sparklines, progress indicators, spotlights, and expression sequences. Installable vabana, vabana-silent, and vabana-gif skills make these expression modes available across supported coding-agent clients.

A local task inspector shows recent sessions, important events, verification evidence, and repository-defined completion criteria without requiring users to read the complete agent transcript.

How we built it

Vabana is a local macOS application built with SwiftUI and AppKit. These power the floating overlay, animations, Card and Pulse interfaces, task inspector, positioning, accessibility behavior, setup wizard, and preferences.

The agent-facing system is a TypeScript monorepo containing:

  • an MCP server;
  • a shared versioned protocol;
  • a coordination runtime;
  • native Codex and Claude Code adapters; and
  • a bounded local projection cache.

Native hook payloads are normalized into a provider-neutral event model. The coordination runtime reduces these events into a compact state containing the agent’s activity, active tool, delegated agent, evidence, and verification posture. A token-authenticated local WebSocket sends this state to the macOS renderer.

Native hooks remain the trusted source for actual harness activity, while MCP tools represent deliberate agent expression. This separation prevents self-reported agent messages from being treated as verified actions.

The project was developed through several AI-assisted iterations using Codex. The ideas were refined using GPT 5.6 and turned into RFC document, which were later seeded as Github issues and Milestone. Codex worked in agile fashion to deliver the stories fulfilling the acceptance criteria.

Challenges we ran into

The largest challenge was noise. Coding agents can emit many events within seconds, especially during parallel tool calls. Displaying each event made the interface distracting.

I solved this with a deterministic presentation policy that deduplicates repeated events, applies cooldowns, suppresses low-value session-start notifications, preserves useful working states, and prioritizes approval requests that need user attention.

Trust and privacy were also important. Vabana distinguishes between what an agent reports and what the coding harness verifies. Native tool inputs and outputs are processed only long enough to derive bounded facts such as check type, result, duration, and test counts. Raw prompts, commands, credentials, and tool output are not stored in the projected task record.

Another challenge was keeping the Swift renderer and TypeScript runtime synchronized. Shared protocol versions, bounded schemas, sanitization, fixtures, and contract tests help keep both implementations consistent.

Accomplishments that we're proud of

Vabana has grown from an experimental emotion overlay into a native embodiment and coordination layer for coding agents.

It can now:

  • automatically represent Coding agent tool activity through native hooks;
  • show provider, tool, and delegated-agent identity;
  • convert noisy event streams into meaningful Pulse or Card feedback;
  • support expressive MCP surfaces ranging from emojis to interactive prompts;
  • install reusable expression skills across supported agent clients;
  • derive verification evidence from native command results;
  • invalidate stale evidence after relevant workspace changes;
  • display tasks, events, checks, and completion criteria locally; and
  • enforce repository-defined definitions of done through supported native stop hooks.

The project is now consistently branded as Vabana and released as version 0.1.1.

What we learned

Transparency does not mean showing everything. A raw stream of events can be as difficult to understand as showing nothing. Useful transparency requires selection, timing, hierarchy, and context.

We also learned that embodiment is most effective when it combines emotion with useful information. An expression becomes more meaningful when users can also see which agent is active, what tool it is using, or whether it needs approval.

Trust depends on provenance. Agent-authored expression, native harness activity, and verified evidence should remain separate so users understand where each claim came from.

Finally, animations, GIFs, sounds, and captions work best as punctuation rather than constant decoration. Vabana therefore uses rate limits, event coalescing, and user-selectable display styles to remain informative without becoming distracting.

What's next for Vabana - Agent Expressions

Vabana is currently an early-alpha macOS project. The next step is to improve installation, packaging, code signing, onboarding, and testing across a wider range of real development environments.

Future work includes supporting more coding agents and operating systems, expanding characters and themes, improving accessibility, simplifying repository verification configuration, and conducting user studies on awareness, cognitive load, and trust.

The long-term goal is to create a lightweight visual language between people and autonomous software—one that communicates not only what an AI agent says, but what it is doing, what has been verified, and when human attention is required.

Built With

Share this project:

Updates