GitHub - icarus-itcs/lazycap: ⚡ A terminal UI for Capacitor development - device management, builds, and live reload in one beautiful interface.

The command center for Capacitor & Ionic mobile development

Quick Start • Features • Shortcuts • AI Integration • Plugins • Config

What is lazycap?

lazycap is a beautiful terminal dashboard for Capacitor and Ionic mobile development. It unifies device management, builds, live reload, debugging, and AI assistance into one elegant interface.

No more juggling terminal windows. No more remembering commands. Just lazycap.

Quick Start

Install

# Homebrew (recommended)
brew tap icarus-itcs/lazycap https://github.com/icarus-itcs/lazycap
brew install lazycap

# Or with Go
go install github.com/icarus-itcs/lazycap@latest

Run

cd your-capacitor-project
lazycap

That's it. lazycap auto-detects your project, discovers devices, and you're ready to go.

Features

Device Management

View all your development targets in one place:

Device Type	Support
iOS Simulators	Full support with boot/status tracking
iOS Physical Devices	USB-connected devices
Android Emulators	Full support with state management
Android Physical Devices	USB debugging enabled devices
Web Browser	Always available

Auto-detection — lazycap finds devices using xcrun simctl, adb, and emulator commands automatically.

One-Key Actions

Everything you need is a single keystroke away:

r — Run on device (with optional live reload)
b — Build web assets
s — Sync to native projects
o — Open in Xcode or Android Studio
x — Kill a running process

Live Reload

Start live reload sessions with smart defaults:

Configurable port (default: 8100)
External host detection for physical devices
Per-device targeting
Auto-sync before run (optional)

Smart Framework Detection

lazycap auto-detects your web framework and finds the right dev command:

Framework	Detection
Vite	`vite.config.*`
Ionic	`ionic.config.json`
Webpack	`webpack.config.*`
Parcel	`.parcelrc`
Next.js	`next.config.*`
Nuxt	`nuxt.config.*`

Falls back to common scripts: dev, serve, start, ionic:serve, dev:web

Process Management

Monitor all your running processes with real-time logs:

Process tabs — Switch between Run, Build, Sync, Web Dev
Live streaming — Watch logs as they happen
Status indicators — See running, success, failed, or canceled
Log actions — Copy to clipboard or export to file

30+ Debug Actions

Press d to access powerful cleanup and diagnostic tools:

iOS/Xcode

Clear Derived Data
Clear Device Support
Clean iOS Build
Reset All Simulators
Deintegrate & Reinstall Pods

Android

Clean Android Build
Clear Gradle Cache
Stop Gradle Daemons
Restart ADB Server
Wipe Emulator Data

Node/Web

Clear node_modules
Clear NPM Cache
Kill Dev Server Ports
Clear Vite/Webpack Cache
Force Rebuild

Nuclear Options

Full Project Clean (all caches)
Fresh Install (clean + npm install + pod install + cap sync)

Preflight Checks

Automatic environment validation on startup:

Node.js, npm, npx, git
Xcode CLI tools & CocoaPods (macOS)
Android SDK & ADB
Capacitor CLI
Version compatibility checks

Monorepo Support

Working in a monorepo? lazycap discovers all Capacitor projects up to 4 levels deep and lets you switch between them with a project selector.

Self-Update

Press U when an update is available to upgrade lazycap in-place. No package manager needed.

Keyboard Shortcuts

Core Actions

Key	Action
`r`	Run on selected device
`b`	Build the project
`s`	Sync Capacitor
`o`	Open in native IDE
`w`	Start web dev server

Navigation

Key	Action
`Tab`	Switch between panes
`↑` `↓`	Navigate lists
`←` `→`	Switch process tabs
`Enter`	Select / Confirm
`Esc`	Back / Cancel

Process Management

Key	Action
`x`	Kill selected process
`c`	Copy logs to clipboard
`e`	Export logs to file

Panels

Key	Action
`d`	Debug tools
`P`	Plugins panel
`,`	Settings
`p`	Preflight checks
`?`	Help

System

Key	Action
`R`	Refresh device list
`U`	Update lazycap
`q`	Quit (press twice)

AI Integration

MCP Server

lazycap exposes functionality via the Model Context Protocol, allowing AI assistants to control your development environment.

Add to Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "lazycap": {
      "command": "lazycap",
      "args": ["mcp"],
      "cwd": "/path/to/your/capacitor-project"
    }
  }
}

Available Tools:

Tool	Description
`list_projects`	List all Capacitor projects
`list_devices`	Get available devices/emulators
`run_on_device`	Run app with optional live reload
`sync`	Sync web assets to native
`build`	Build web assets
`open_ide`	Open Xcode or Android Studio
`get_project`	Get project information
`get_all_logs`	Get logs with filtering (type, status, search, errors_only)
`get_debug_actions`	List debug/cleanup actions
`run_debug_action`	Execute a debug action

Log Filtering Options:

The get_all_logs tool supports powerful filtering:

type — Filter by process type: "build", "sync", "run", "web", or plugin name like "firebase"
status — Filter by status: "running", "success", "failed", "canceled"
search — Search for text in logs (case-insensitive)
errors_only — Only return lines containing error indicators
tail — Limit lines per process

Example prompts for Claude:

"Run the app on my iPhone simulator with live reload"

"Sync the project and open it in Xcode"

"The build failed, check the logs and fix the error"

"Show me only the error lines from the last build"

"What's happening with the firebase emulator?"

"Clear all caches and do a fresh install"

Plugins

lazycap features an extensible plugin system. Press P to manage plugins.

MCP Server Plugin

Exposes lazycap via Model Context Protocol for AI assistant integration.

Setting	Description	Default
`mode`	`tcp` or `stdio`	`tcp`
`port`	TCP port	`9315`
`autoStart`	Start on launch	`false`

Firebase Emulator Plugin

Integrates Firebase Emulator Suite for local development.

Supported Emulators: Auth, Firestore, Realtime Database, Functions, Hosting, Storage, PubSub, Eventarc

Setting	Description	Default
`autoStart`	Start on launch	`false`
`exportOnExit`	Export data on stop	`true`
`exportPath`	Export directory	`.firebase-export`
`uiEnabled`	Enable Emulator UI	`true`

Plugin API

Create custom plugins by implementing the Plugin interface:

type Plugin interface {
    ID() string
    Name() string
    Description() string
    Version() string

    Init(ctx Context) error
    Start() error
    Stop() error
    IsRunning() bool

    GetSettings() []Setting
    GetStatusLine() string
    GetCommands() []Command
}

Plugins can access devices, processes, logs, settings, debug actions, and the event bus.

Configuration

Settings File

lazycap supports both per-project and global settings:

Location	File	Priority
Per-project	`.lazycap.json` in current directory	Checked first
Global	`~/.config/lazycap/settings.json`	Fallback

When you modify settings, they're saved to the currently loaded config file (shown at the bottom of the settings panel). New settings default to per-project config in the current directory.

Press , to open the settings panel.

Run Options

Setting	Description	Default
`liveReloadDefault`	Enable live reload by default	`false`
`liveReloadPort`	Live reload port	`8100`
`externalHost`	External IP (auto-detect if empty)	—
`autoSync`	Sync before running	`false`
`autoBuild`	Build before syncing	`false`
`clearLogsOnRun`	Clear logs on new run	`true`

Build Options

Setting	Description	Default
`buildCommand`	Custom build command	auto-detect
`productionBuild`	Use production mode	`false`
`sourceMaps`	Generate source maps	`true`
`buildTimeout`	Timeout in seconds	`300`

iOS Options

Setting	Description	Default
`iosScheme`	Xcode scheme	—
`iosConfiguration`	Debug or Release	`Debug`
`iosAutoSigning`	Automatic signing	`true`
`iosTeamId`	Development team ID	—

Android Options

Setting	Description	Default
`androidFlavor`	Build flavor	—
`androidBuildType`	debug or release	`debug`
`androidSdkPath`	Custom SDK path	—

Web Dev Options

Setting	Description	Default
`webDevCommand`	Dev server command	auto-detect
`webDevPort`	Dev server port	—
`webOpenBrowser`	Auto-open browser	`false`
`webHttps`	Use HTTPS	`false`

UI Options

Setting	Description	Default
`compactMode`	Compact UI layout	`false`
`showTimestamps`	Timestamps in logs	`false`
`showSpinners`	Animated spinners	`true`
`colorTheme`	dark, light, system	`dark`
`maxLogLines`	Max lines per log	`5000`

CLI Commands

lazycap              # Launch the TUI dashboard
lazycap version      # Show version, commit, build date
lazycap devices      # List devices in table format
lazycap mcp          # Run as MCP server
lazycap --demo       # Demo mode with mock data
lazycap --verbose    # Verbose output
lazycap --config     # Custom config file path

Platform Support

Platform	Architecture	Status
macOS	Apple Silicon (arm64)	Tested
macOS	Intel (amd64)	Supported
Linux	64-bit (amd64)	Supported
Linux	ARM64	Supported
Linux	32-bit / ARMv7	Supported
Windows	64-bit / ARM64	Untested
FreeBSD	64-bit	Supported

Requirements

Core:

Node.js 18+ with npm/yarn/pnpm
Capacitor project (capacitor.config.ts/js/json)

iOS Development (macOS only):

Xcode with command line tools
CocoaPods
iOS Simulator or physical device

Android Development:

Android Studio with SDK
ADB
Emulator or physical device (USB debugging enabled)

Troubleshooting

Debug Log

Check /tmp/lazycap-debug.log for detailed information.

Common Issues

Devices not showing?

Run preflight checks (p) to verify tools are installed
For iOS: Ensure Xcode CLI is installed (xcode-select --install)
For Android: Ensure ADB is running (adb devices)

Live reload not connecting?

Check externalHost setting for physical devices
Verify firewall allows the live reload port

Build failing?

Use debug tools (d) to clean caches
Try "Fresh Install" for a complete reset

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Ways to help:

Report bugs and suggest features
Submit pull requests
Improve documentation
Create and share plugins
Test on different platforms

Development

git clone https://github.com/icarus-itcs/lazycap.git
cd lazycap
go mod download
make build
./bin/lazycap

License

MIT + Commons Clause — Free to use, modify, and share. You just can't sell it.

Use lazycap for any project (personal or commercial)
Modify and fork the code
Contribute improvements back
Share with others

The Commons Clause prevents reselling lazycap or offering it as a paid service.

Acknowledgments

Built with Bubble Tea — The fun, functional framework for terminal UIs
Inspired by lazygit and lazydocker
Designed for the Capacitor community

Made with care by Icarus, Inc.

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github		.github
Formula		Formula
assets		assets
cmd		cmd
internal		internal
scripts		scripts
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
RELEASING.md		RELEASING.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Folders and files

Latest commit

History

Repository files navigation

What is lazycap?

Quick Start

Install

Run

Features

Device Management

One-Key Actions

Live Reload

Smart Framework Detection

Process Management

30+ Debug Actions

Preflight Checks

Monorepo Support

Self-Update

Keyboard Shortcuts

Core Actions

Navigation

Process Management

Panels

System

AI Integration

MCP Server

Plugins

MCP Server Plugin

Firebase Emulator Plugin

Plugin API

Configuration

Settings File

Run Options

Build Options

iOS Options

Android Options

Web Dev Options

UI Options

CLI Commands

Platform Support

Requirements

Troubleshooting

Debug Log

Common Issues

Contributing

Development

License

Acknowledgments

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 13

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages