TL;DR

  • Candle은 컨테이너 없이 프로젝트 디렉터리별로 로컬 개발 서비스를 백그라운드에서 관리하는 도구임.
  • macOS와 Linux를 지원하며, 프로세스 상태와 로그를 SQLite 데이터베이스에 저장함.
  • 서로 다른 작업 트리(worktree)는 각각 독립된 프로세스 집합을 가지며, 포트 할당은 직접 해결해야 함.
  • 코딩 에이전트가 대기형 명령을 실행하지 않도록 candle watch 대신 즉시 반환하는 candle logs를 안내함.
  • 포트 확인, 브라우저 열기, 로그 메시지 대기 기능을 제공하며 1.0 릴리스를 준비 중임.

빠른 시작

  • Candle은 macOS와 Linux에서 지원됨.
  • macOS에서는 Homebrew로 설치하거나, macOS와 Linux에서 설치 스크립트를 실행해 설치할 수 있음.
  • Homebrew 설치 명령은 brew install facetlayer/tap/candle임.
  • 직접 설치 명령은 curl -fsSL https://raw.githubusercontent.com/facetlayer/candle/main/install.sh | sh임.
  • 설치 후 candle --help를 실행하면 전체 명령 목록을 확인할 수 있음.
  • 코딩 에이전트가 Candle을 사용하도록 AGENTS.md에 다음 지침을 추가할 수 있음.
  • 로컬 개발 서비스 실행에는 candle CLI를 사용하고, 실행 중인 서비스는 candle ps, 프로세스 로그는 candle logs로 확인함.
  • 다른 명령과 문서는 candle --help로 확인함.

개발 배경

  • Candle 개발은 2025년 7월 시작됨. 당시 Claude Code에는 프로세스를 비동기 백그라운드에서 실행하는 방법이 없어, 이를 해결하기 위해 Claude용 MCP 서버로 도구를 작성함.
  • 현재 Claude Code와 다른 하네스에는 백그라운드 프로세스를 실행하는 내장 기능이 개선됐지만, Candle은 여전히 유용하게 쓰임.
  • 지난 1년간 개발 프로젝트 전반에서 사용하며 여러 작동 방식을 반복해 개선했고, 현재는 안정화돼 1.0 릴리스 준비가 된 상태임.

설계

컨테이너 기반이 아님

  • 로컬 개발에 Docker 컨테이너를 사용하지 않는 설계임.
  • 컨테이너 기반 개발을 원한다면 Docker Compose 같은 기존 도구를 사용할 수 있음.

프로세스는 백그라운드에서 실행됨

  • Candle은 프로세스를 백그라운드에서 관리하므로, 서비스가 현재 세션이나 터미널이 끝난 뒤에도 실행될 수 있음.
  • 이는 pm2 같은 일반적인 프로세스 관리자와 비슷하며, 프로세스를 포그라운드에서 실행하는 Foreman 같은 로컬 개발 도구와 다름.
  • 여러 터미널 세션이 같은 프로세스를 공유할 수 있으며, 현재 세션에서 시작하지 않은 프로세스도 candle logs와 candle watch로 확인할 수 있음.
  • ~/.local/state 디렉터리의 단일 SQLite 데이터베이스에 로그와 프로세스 상태를 저장해 중앙에서 관리함.

프로세스는 프로젝트 디렉터리별로 분리됨

  • candle ps나 candle start를 실행하면 현재 프로젝트 디렉터리에 속한 프로세스만 표시하거나 생성함. 다른 프로젝트 디렉터리에서 실행하면 별도의 프로세스 집합을 확인함.
  • ~/dev/worktree-1과 ~/dev/worktree-2처럼 서로 다른 작업 트리는 완전히 독립된 프로세스 집합을 가짐.
  • 첫 번째 작업 트리에서 candle start api를 실행하면 npm run api 프로세스가 시작되며, candle ps에 api의 상태와 PID, 실행 시간이 표시됨.
  • 두 번째 작업 트리에서 candle ps를 실행하면 api는 실행 중이 아닌 상태로 표시됨. 해당 디렉터리에서 candle start api를 실행하면 별도의 npm run api 프로세스가 시작됨.
  • 폴더별로 프로세스를 격리해 해당 폴더와 관련된 프로세스만 보이도록 하는 단순하고 방해가 적은 방식임. 현재 프로젝트 디렉터리를 암묵적으로 기준으로 삼는 Git CLI의 작동 방식과 비슷함.

포트 할당 관련 참고 사항

  • 여러 작업 트리에서 같은 서비스를 실행하면 동일한 포트를 두 번 사용해 충돌할 수 있으므로, 고유한 포트 할당 방법이 필요할 가능성이 큼.
  • 내장 포트 관리 기능을 구현해 보았으나 도구가 훨씬 복잡해져, 적어도 1.0 버전에서는 고유 포트 할당을 지원하지 않음.
  • 각 작업 트리 디렉터리에 고유한 포트 번호의 환경 변수를 정의한 .env 파일을 두는 방식 등 별도의 전략이 필요함.

코딩 에이전트 우선 지원

  • 앞서 설명한 디렉터리별 프로세스 분리를 비롯해 코딩 에이전트와의 사용성을 높이는 여러 세부 구현이 포함됨.
  • 에이전트가 블로킹되거나 상호작용이 필요한 명령을 실행하지 않도록 유도함. 특히 candle watch는 사용자가 Ctrl-C를 누를 때까지 로그를 실시간 스트리밍하므로, 사람에게는 유용하지만 코딩 에이전트에는 적합하지 않음.
  • 장시간 실행 프로세스에서 에이전트가 완료를 잘못 기다리거나 작업 후 프로세스를 종료하지 않는 실수를 할 수 있음.
  • Candle은 에이전트가 watch를 호출하는 것으로 감지하면 오류를 출력하고 candle logs를 사용하도록 안내함. logs는 즉시 반환되므로 에이전트에 더 적합함.

편의 명령

  • 개발 과정에서 유용했던 편의 명령을 제공함.
  • candle list-ports는 운영체제를 확인해 서비스가 실제로 수신 대기 중인 포트를 찾음.
  • candle open-browser는 같은 포트 확인 기능을 사용해 웹 서비스로 추정되는 http://localhost:<your port> 주소를 브라우저 창에서 엶.
  • candle wait-for-log ...는 특정 로그 메시지가 나타날 때까지 제한 시간과 함께 대기함. 서비스가 완전히 시작된 뒤 기능·통합 테스트를 실행해야 하는 CI 작업에서 사용할 수 있음.

설치