(AI usage: No AI was used in writing this post)
Candle is a development tool I built (with the help of AI coding agents) for managing local services during development.
It's a process manager like systemd, pm2, supervisor, etc, but it's specifically
designed for local development. So the usage is much simpler than other tools that
are designed to manage services in production. It's similar to Foreman but makes some different decisions (listed below).
Overall it's designed to work really well with coding agents, worktrees, and humans too. Hopefully you find it useful too.
Quick Start
Candle is supported on Mac & Linux:
To get started with Homebrew on Mac:
brew install facetlayer/tap/candle
Or direct installation for Mac & Linux:
curl -fsSL https://raw.githubusercontent.com/facetlayer/candle/main/install.sh | sh
At that point run candle --help for the full list of commands.
And you can add this text to your AGENTS.md to get your coding agent to use it:
Backstory
Candle development started in July 2025. At the time, Claude Code didn't have a way to run processes in the background in a non-blocking way, so I wrote the tool as an MCP server for Claude to fix that.
Today, Claude Code and the other harnesses do have a much better builtin ability to run backgrounded processes. But I've found that Candle is still pretty useful.
So in the past year I've been using Candle for all my dev projects, and have iterated and experimented with various approaches for how it works, and at this point it's stable and ready for a 1.0 release.
The design
Here are some of the major design decisions that Candle has:
1. Not container based
One decision right off the bat is that I don't like to use Docker containers for local development. If you want to do container-based development, then there are other great existing tools for that, like Docker Compose.
2. Processes are run in the background
Candle manages processes in the background, which means that a service can be launched in a way that outlives the current session or terminal.
This matches 'real' process managers like pm2. It's different than other
local-focused tools like Foreman, which runs its processes in the foreground.
The benefit is that multiple terminal sessions can work on the same shared processes.
Commands like candle logs and candle watch
can look at processes that weren't launched by the current session.
The way it's centralized is through a single SQLite database in your ~/.local/state directory that stores logs and process states.
3. Processes are scoped by project directory
This decision is a little more interesting and most process managers don't work this way.
Whenever you run commands like candle ps or candle start, the processes that are listed
or created are all local to the current project directory. If you run candle in a different
project, you'll see a different set of processes.
So, you can have worktrees like ~/dev/worktree-1 and ~/dev/worktree-2,
and since those are different directories, they will have a completely independent set of processes.
Example of what it might look like:
~/dev/worktree-1 $ candle start api
[Started process 'api'] $ npm run api
~/dev/worktree-1 $ candle ps
NAME STATUS PID UPTIME
---- ------- ----- ------
api RUNNING 71497 2s
~/dev/worktree-1 $ cd ../worktree-2
~/dev/worktree-2 $ candle ps
NAME STATUS PID UPTIME
---- ----------- --- ------
api not running - -
~/dev/worktree-2 $ candle start api
[Started process 'api'] $ npm run api
This helps the tool behave in a simple way. Each folder is more isolated, and you only see processes related to that folder. This helps keep things more simple and distraction-free for your agent and you.
It's similar to the way the git CLI works, which also operates implicitly on the current project directory.
Notes on port assignment
One thing to call out is that if you're using multiple worktrees, you'll probably need some solution for unique port assignment. Otherwise trying to launch the same service twice with the same port will conflict.
I tried implementing a version of Candle that had builtin support for port management,
but it made the tool a lot more complicated, so (in the 1.0 version at least), Candle doesn't help with unique port assignment.
So, you'll need some other strategy. The solution could be a .env
file in each worktree directory, which has environment variable definitions with unique port numbers.
4. First class support for coding agents
Candle has lots of small implementation choices to help it work better with coding agents, in addition to the things mentioned above (especially directory-scoped processes).
One of these is that Candle will try to stop your agent from running commands that are
blocking or interactive. Specifically the
candle watch command. What the watch command does is enter a mode where it streams logs
as they happen, until the user kills it with Ctrl-C. It's great for humans but not ideal for coding agents.
With long-running processes, agents can make mistakes where they wrongly wait for the whole process to finish, or
maybe they forget to close the process when it's done.
So, if Candle detects that an agent is calling watch, it just prints an error and tells
it to use candle logs instead. The logs command returns immediately, so it works much
better for agents.
5. Various quality of life commands
The tool also ships with a few QOL commands that I've found pretty useful along the way.
It includes port-checking commands like candle list-ports, which checks the operating
system to find which ports your services are actually listening on.
Related to this is
candle open-browser which uses the same port checking feature to open a browser window to look at http://localhost:<your port>
(assuming your service is a web service).
Another one is candle wait-for-log ... which blocks (with a timeout) until a certain log message
appears. This one works great in CI jobs that run functional/integration tests.
You can use candle commands in the job to make sure that the service fully starts up, before
starting the test run.
Installation
Anyway that's the tool! If you're interested in using Candle, installation instructions are here: https://github.com/facetlayer/candle#installation