kestrel

Context engineering for humans in an agentic multitasking world.
_{A GNOME Shell extension that gives each project its own workspace — agent, browser, files — in a scrollable strip you supervise at a glance.}

Project Site · Install · Keybindings · Claude Code · Development

---

The Problem

Agentic tasks keep getting longer. You're no longer writing code — you're supervising multiple AI agents working across multiple projects in parallel. The idle time between interactions grows, so you context-switch constantly. But your OS was designed for a world where you do one thing at a time. Alt-Tab through five terminals? You lose track. Scatter them across virtual desktops? You miss a permission request. Everything stalls silently.

What Kestrel Does

Kestrel gives each project its own workspace — agent terminal, browser, reference files — arranged in a horizontal strip you scroll through. Status badges show which agents are working, waiting, or done. Permission requests surface inline. Workspaces stack vertically for context separation. You see everything, switch effortlessly, and miss nothing.

            ← scroll →

        ┌────────┬────────┬────────┬────────┐
   W0   │  agent │  agent │  agent │  agent │
        ├────────┼────────┼────────┼────────┤
   W1   │  docs  │ browser│        │        │
        ├────────┼────────┼────────┼────────┤
   W2   │  slack │  notes │  term  │        │
        └────────┴────────┴────────┴────────┘

        ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
        └── your view ───┘

Features

• Scrolling tiling — windows in horizontal strips, half or full monitor width
• Agent status badges — see which Claude Code sessions are working, waiting, or done
• Permission overlays — approve or deny tool requests without switching windows
• Virtual workspaces — stacked vertically, created and removed dynamically
• Bird's-eye overview — see all workspaces at once, navigate with keyboard or click
• Multi-monitor — monitors combine into a single panoramic viewport
• State persistence — layout survives screen lock and extension restarts
• Keyboard-first — every action has a binding, everything is rebindable

Requirements

• GNOME Shell 45+ (Wayland or X11)
• Node.js 18+ and npm (for building)
• Claude Code (optional, for agent integration features)

Install

git clone https://github.com/notiriel/kestrel.git
cd kestrel
npm install
make install    # Build + deploy to GNOME extensions dir
make enable     # Enable extension + Claude Code plugin + disable conflicting extensions

Then restart your session (log out and back in on Wayland, or Alt+F2 → r → Enter on X11).

Check installation status:

make status

What happens during install

make install compiles TypeScript, copies the extension to ~/.local/share/gnome-shell/extensions/, compiles GSettings schemas, and symlinks the Claude Code plugin and Ulauncher extension.

make enable enables the GNOME extension, disables conflicting extensions (Ubuntu tiling-assistant, DING, Ubuntu Dock), and enables the Claude Code plugin in ~/.claude/settings.json.

Keybindings

All keybindings are configurable via GSettings.

Keybinding	Action
Super+Right	Focus next window
Super+Left	Focus previous window
Super+Down	Switch to workspace below
Super+Up	Switch to workspace above
Super+F	Toggle window half/full width
Super+Shift+Right	Move window right
Super+Shift+Left	Move window left
Super+Shift+Down	Move window to workspace below
Super+Shift+Up	Move window to workspace above
Super+-	Toggle overview
Super+N	Open new window of focused app
Super+.	Toggle notification focus mode

Kestrel takes over the Super key and several default GNOME keybindings. make disable restores all original bindings.

Claude Code Integration

Kestrel includes a Claude Code plugin that connects your AI sessions to the desktop via DBus:

• Session tracking — each Claude Code terminal is mapped to its window automatically
• Status badges — window clones show live session status (working / needs-input / done)
• Permission cards — tool permission requests appear as overlay cards you can approve or deny inline
• Notifications — fire-and-forget status updates from Claude Code sessions

The integration activates automatically when Claude Code is installed and the plugin is enabled.

Development