Skip to content

README.md

Latest commit

 

History

History
220 lines (174 loc) · 10.1 KB

README.md

File metadata and controls

220 lines (174 loc) · 10.1 KB
Raw
Runway app icon

Runway

Your GitHub issues, coding agents, and terminals in one native macOS workspace.

Latest release macOS 14 or newer Swift 6 MIT license

Download · Features · Agent integration · Build locally

Runway is a native cockpit for people who work with several coding agents at once. It connects assigned GitHub issues, persistent GPU terminals, repository activity, and pull request progress in one focused workspace.

Install in a minute

  1. Download Runway-2.1.0-arm64.dmg from GitHub Releases.
  2. Open the DMG and drag Runway.app onto Applications.
  3. Launch Runway.

Runway is currently ad-hoc signed and not notarized. If macOS reports that the app is damaged or unverified, clear the download quarantine once:

xattr -dr com.apple.quarantine /Applications/Runway.app

Requirements:

  • Apple Silicon Mac running macOS 14 or newer
  • GitHub CLI authenticated with gh auth login for issues, feeds, people, repositories, and pull requests

The terminal workspace still works without GitHub CLI. GitHub-backed views need an authenticated session.

What you get

Capability Why it matters
🖥️ Persistent GPU terminals Run Claude Code, Codex, Gemini, custom agents, or a normal shell in fast libghostty-backed cards.
📡 Live GitHub activity See pushes, pull requests, reviews, issues, branch activity, and who has been active recently.
⚡ Quick terminal Toggle a persistent overlay with ⌘⌥Q without losing its session.
🧭 Issue-driven Focus board Drag assigned GitHub issues into Focus to create matching terminals automatically.
🟢 Agent-aware status Cards can report idle, running, or needs-action, plus their current task and description.
🔔 Native notifications Get macOS alerts and configurable sounds when an agent needs attention.
💾 Local-first workspace cache Issues, Focus terminals, ordering, working directories, and pane position appear immediately after relaunch.
🎨 Custom branding Replace the Activity heading with your own text or a persistent SVG, PNG, JPEG, or other macOS-supported image.
📊 Pull request overview Compare open and merged pull requests by developer across practical timeframes.
👥 People profiles Edit local usernames, full names, and avatars consistently across Runway.

The activity side

Runway discovers cloned GitHub repositories on your Mac, then polls the selected repository through your existing authenticated gh session. There is no separate token setup and no personal access token stored by the app. Cached Feeds, issues, Pulls, and local repository choices render immediately, then revalidate in the background. Identical requests are coalesced across windows, reads are concurrency-limited, failures back off automatically, and routine polling pauses while Runway is inactive.

  • A presence strip shows who has been active recently.
  • The timeline groups meaningful pushes, PR activity, reviews, issues, and branch changes.
  • Runway, Feeds, and Pulls tabs separate focused work, repo motion, and pull request activity. Feeds includes an optional merge-only filter.
  • The Pulls view groups pull requests by developer, sorts developers by merged PRs, and supports 1d, 7d, 30d, MTD, and YTD timeframes. Timeframes use creation time for open PRs, merge time for merged PRs, and close time for closed PRs.
  • The Runway board shows assigned Open and Closed issues, supports local ordering, and can close or reopen issues on GitHub through drag and drop.
  • Click On today's missions to smoothly collapse or expand the Focus board while keeping the Open and Closed issue backlog visible.
  • ⌘F opens tab-specific search for issues, feed events, or pull requests.
  • The searchable repo switcher shows only GitHub repositories cloned on this Mac. Opening it refreshes the local clone list.
  • Pull to refresh, infinite history loading, and skeleton states keep the feed responsive.

GitHub's events API is not real time. Events may lag by a minute or two and only cover recent history, so presence is a useful signal rather than an attendance system.

The terminal side

The Focus board is the source of truth for the right pane. Each focused issue creates a terminal with the issue title, stable shell session, and the selected repository's local clone as its starting directory. For example, VISKA-IO/monorepo starts in ~/Developer/monorepo when that is its local clone.

  • Accordion layout always fits every focused terminal into the available window height and gives the active terminal more space.
  • Focus terminal headers are issue-owned and read-only. The right-side #1234 reference copies the issue number when clicked.
  • Focus mode expands the active terminal to fill the pane.
  • Quick terminal stays alive behind its bottom-left overlay.
  • Switching repositories keeps each repository's Focus terminals and running agent sessions alive, then restores them when that repository is selected again.
  • Double-click the top window edge or blank left-header space to fill the screen; double-click it again to restore the previous window size and position.
  • File drops insert shell-escaped paths directly into the target terminal.
  • Agent commands can start as Claude, Codex, Agent, a custom command, or a plain shell.

Agent-native by design

Every Runway terminal receives a small local control API. Any agent or script can update its card without a plugin or network service:

# Rename the card and describe the current task
echo '{"name":"checkout-fix","description":"running integration tests"}' > "$RUNWAY_CONTROL"

# Update the status dot
echo '{"state":"running"}' > "$RUNWAY_CONTROL"
echo '{"state":"needs-action"}' > "$RUNWAY_CONTROL"
echo '{"state":"idle"}' > "$RUNWAY_CONTROL"

Focus terminal titles and issue references are owned by their GitHub issues and remain read-only. name and description updates apply only to non-Focus agent cards; state updates continue to work for Focus terminals.

Run this inside any card to discover everything an agent can do:

runway-help

Every issue entering or leaving the Focus board is appended to the machine-readable JSONL journal at $RUNWAY_FOCUS_LOG. Agents can filter it by timestamp to reconstruct what was in Focus during a time range, then enrich that history with git or session data. runway-focus-log prints the journal from any Runway terminal.

Wrap any command-line agent for automatic running and idle status:

runway-agent codex
runway-agent gemini
runway-agent my-custom-agent --flag

Claude Code gets richer automatic attention hooks when launched normally as claude. The guide and helper commands live inside Runway's Application Support directory. Runway does not edit your shell or agent configuration files.

Keyboard map

Move Shortcut Action
Focus ⌘⌥↑ / ⌘⌥↓ Move between agents
Jump ⌘1 through ⌘9 Focus a specific agent
Focus mode ⌘⌥⏎ Expand or restore the active terminal
Quick terminal ⌘⌥Q Show or hide the quick terminal
Close window ⌘⇧W Close the current window
Find ⌘F Search the active Runway, Feeds, or Pulls tab
Change tab ⌘⌥1 through ⌘⌥3 Open Runway, Feeds, or Pulls
Settings ⌘, Open settings and people profiles

Shortcuts can be customized from Runway → Settings → Shortcuts.

Privacy and local state

  • GitHub requests run through your local authenticated gh CLI.
  • Agent control files, workspace state, cached feed and issue data, and helper scripts stay under ~/Library/Application Support/Runway.
  • Runway does not install skills into Claude, Codex, Gemini, or other agent configuration directories.
  • Runway does not modify .zshrc, .claude, or equivalent user configuration files.

Developing Runway

Runway is a Swift Package and does not require an Xcode project.

./run.sh                 # debug build, install, and relaunch the app bundle
./watch.sh               # rebuild and relaunch after Swift source changes
./build-app.sh debug     # assemble dist/Runway.app
./build-app.sh release   # optimized app-bundle build
./package-dmg.sh         # create the drag-to-install release DMG

build-app.sh bundles the libghostty framework and signs the complete app bundle ad hoc. relaunch.sh replaces /Applications/Runway.app and opens it through the macOS GUI session.

Project map 
Sources/Runway/
  Core/         App lifecycle, windows, keyboard monitors, notifications
  Models/       Agent cards, workspace persistence, people profiles
  Services/     GitHub data, Focus history, caching, local control API
  Terminal/     Ghostty host, terminal sessions, quick terminal, theme
  Utils/        Key bindings, pointer behavior, inline editing
  Views/        Activity feed, terminal cards, settings, profiles

GhosttyKit is pinned to a known commit in Package.swift because libghostty's C API is still evolving.

License

Runway is available under the MIT License.