https://github.com/kyonru/feather
Debugging, runtime inspection, profiling, remote sessions, and developer workflows for Löve2D games.
https://github.com/kyonru/feather
cli debugger devtool gamedev logs love2d lua monitoring package-manager plugin-system
Last synced: 11 days ago
JSON representation
Debugging, runtime inspection, profiling, remote sessions, and developer workflows for Löve2D games.
- Host: GitHub
- URL: https://github.com/kyonru/feather
- Owner: Kyonru
- License: epl-2.0
- Created: 2025-08-05T01:26:13.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-05-24T22:12:51.000Z (20 days ago)
- Last Synced: 2026-05-25T00:32:53.292Z (20 days ago)
- Topics: cli, debugger, devtool, gamedev, logs, love2d, lua, monitoring, package-manager, plugin-system
- Language: TypeScript
- Homepage: https://kyonru.github.io/feather/
- Size: 17.5 MB
- Stars: 31
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Feather — CLI Debugging, Inspection, and Builds for LÖVE
> [!IMPORTANT]
> This is the dev version of Feather, for stable releases go to the [release page](https://github.com/Kyonru/feather/releases).
[](https://github.com/Kyonru/feather/releases)
[](https://www.npmjs.com/package/@kyonru/feather)
[](https://www.npmjs.com/package/@kyonru/feather)
[](https://marketplace.visualstudio.com/items?itemName=SolenodonteLabs.feather-cli-vscode)
[](https://luarocks.org/modules/kyonru/feather)
Feather is a CLI for debugging, inspecting, and manage packages for [LÖVE](https://love2d.org) games.
It gives you a live window into your running game _(logs, variables, errors, performance)_ without touching your game's release build. Inspired by [LoveBird](https://github.com/rxi/lovebird) and [Flipper](https://github.com/facebook/flipper).
The goal is to make the day-to-day loop of writing and testing a LÖVE game faster: less time adding print statements and restarting, more time actually building.
**[✨ Demo](https://feather-showcase.up.railway.app)** · **[📖 Documentation](https://kyonru.github.io/feather)** · [Releases](https://github.com/Kyonru/feather/releases) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)
---
## What it does
- **Live log viewer** — See `print()` output in real time without a terminal window.
- **Variable inspection** — Watch values update as the game runs.
- **Error capturing** — Errors are caught and shown with a full stack trace.
- **Step debugger** — Breakpoints, step over/into/out, call stack, local variable inspection.
- **Session Replay** — Record inputs plus game-defined state checkpoints so playthroughs can be replayed, exported, and debugged later.
- **Console / REPL** — Execute Lua in the running game (opt-in, requires an `apiKey`).
- **Plugin system** — 18+ built-in plugins (collision debug, animation inspector, audio debug, particle editor, and more). Plugins define their UI in Lua; the desktop app renders it automatically.
- **Multi-session** — Connect multiple games at the same time.
- **Mobile and platform builds** — CLI-managed web, Android, iOS, Windows, macOS, Linux, and SteamOS workflows.
- **Screenshots & GIF capture** — Built-in capture plugin.
- **Log file viewer** — Open `.featherlog` files for offline inspection.
- **CLI** — No Lua changes needed to run, debug, build, or clean up love2d games.
- **Package Manager** — Install packages from a curated list of popular love2D packages.
---
---
## Quick Start
Install the Feather desktop app and CLI:
1. Download the desktop app from [Releases](https://github.com/Kyonru/feather/releases).
2. Install the CLI:
```bash
npm install -g @kyonru/feather
```
Initialize your project, open the Feather app, then run the game:
```bash
feather init path/to/my-game
feather run path/to/my-game
```
Feather is injected by the CLI for dev runs and debug builds, so your game code does not need a manual `require` for any target.
Optional vendor setup for web, mobile, and packaged desktop workflows:
```bash
feather build vendor add web --dir path/to/my-game
feather run path/to/my-game --target web
feather build vendor add android --dir path/to/my-game
feather run path/to/my-game --target android
feather build vendor add ios --dir path/to/my-game
feather run path/to/my-game --target ios
```
For all build vendors, including desktop packaging runtimes:
```bash
feather build vendor add all --dir path/to/my-game
```
Build release artifacts from the same CLI flow:
```bash
feather build love --dir path/to/my-game
feather build android --dir path/to/my-game --release
feather build ios --dir path/to/my-game --release
feather build windows --dir path/to/my-game
feather build macos --dir path/to/my-game
feather build linux --dir path/to/my-game
feather build steamos --dir path/to/my-game
```
For more commands and options:
```bash
feather --help
feather run --help
```
See the [CLI docs](docs/cli.md) for `feather run`, `feather doctor`, `feather build`, and `feather upload`.
---
## Package manager
Feather includes a curated installer for common LÖVE libraries. It is not a general package manager — it is a hand-picked catalog of known-good libraries with verified SHA-256 checksums and a lockfile you can commit.
```sh
feather package install anim8 # install a library
feather package install # restore everything in feather.lock.json
feather package audit # verify checksums of installed files
feather package list # browse the catalog
```
Available libraries include anim8, bump, hump, lume, flux, inspect, middleclass, classic, push, sti, and windfield. See [packages/README.md](packages/README.md) for the full list and command reference.
---
## [Documentation](https://kyonru.github.io/feather)
- [Installation](docs/installation.md)
- [CLI](docs/cli.md)
- [Configuration](docs/configuration.md)
- [Usage](docs/usage.md) — observers, logging, console, step debugger
- [Session Replay](docs/session-replay.md)
- [Plugins](docs/plugins.md)
- [Packages](packages/README.md)
- [Recommendations](docs/recommendations.md) — security, performance, release builds
---
## Built-in Lua dependencies
- [Hump Class](https://github.com/vrld/hump/blob/master/class.lua)
- [Inspect](https://github.com/kikito/inspect.lua)
- [json.lua](https://github.com/rxi/json.lua)
- [log.lua](https://github.com/rxi/log.lua)
- [ws.lua](https://github.com/flaribbit/love2d-lua-websocket)
---
## Credits
- [LoveBird](https://github.com/rxi/lovebird) by rxi — original inspiration
- [Love-Dialogue](https://github.com/Miisan-png/Love-Dialogue) by Miisan-png — plugin system reference
- [HUMP](https://github.com/vrld/hump), [anim8](https://github.com/kikito/anim8), [flux](https://github.com/rxi/flux), [bump.lua](https://github.com/kikito/bump.lua), [lua-state-machine](https://github.com/kyleconroy/lua-state-machine)
- [love2d-community/awesome-love2d](https://github.com/love2d-community/awesome-love2d?tab=readme-ov-file#animation) - Inspiration for package helpers
- [GitHub Theme for VS Code](https://github.com/primer/github-vscode-theme) by Primer — optional app theme palettes
- [Noctis](https://github.com/liviuschera/noctis) by Liviu Schera — optional app theme palettes
- [Rainglow](https://github.com/rainglow/vscode) by Dayle Rees — optional app theme palettes
- [Tokyo Night](https://github.com/tokyo-night/tokyo-night-vscode-theme) by Enkia — optional app theme palettes
- [Microsoft C/C++ Themes](https://github.com/microsoft/vscode-cpptools/tree/main/Themes) — optional Visual Studio C/C++ theme palettes
---
## License
The license applies to products that directly replicate the logic or purpose of this tool. It does not apply to games built using it as a development tool.
See [LICENSE.md](LICENSE.md).
## AI usage
The architecture and planning of this tool is my own work. The main goal of this tool is to improve developer experience, meaning providing utilities to save time for my own developer experience and hopefully others. AI autocompletion is used for the creation of some of the features in this tool. This is not an AI driven tool nor a product designed by AI. This is a devtool made by an indie dev for indie devs nothing else. All generated code is reviewed by me. But I understand some people are not comfortable with AI involvement in any form. I respect that.