PTD는 사람과 AI 에이전트의 작업 시간·비용을 함께 기록한다

PTD는 사람과 AI 에이전트가 함께 일하는 팀을 위한 오픈코어 작업 관리 도구다. 작업 계획과 시간 기록을 한곳에서 관리하며, 에이전트가 작업별로 사용한 토큰과 API 비용도 기록할 수 있다.

PTD는 하나의 조직과 공유 작업 목록을 중심으로 네 가지 화면을 제공한다.

각 시간 기록에는 작업을 사람이 했는지 에이전트가 했는지가 표시된다. 에이전트 기록에는 사용 토큰과 API 비용도 포함할 수 있어, 프로젝트 매니저가 위임한 작업의 에이전트 비용과 사람의 작업 시간을 작업별로 살펴볼 수 있다.

무료로 영구 이용할 수 있는 자체 호스팅 버전은 다음 명령으로 실행한다.

git clone https://github.com/danimoya/ptd && cd ptd
cp .env.example .env # set DB_PASSWORD and JWT_SECRET
docker compose up -d --build # http://localhost:3001

기본 데이터베이스는 HeliosDB-Nano이며 docker-compose.yml에서 설정과 함께 구성된다. 앱은 Postgres 와이어 프로토콜을 사용하고 마이그레이션은 일반 SQL이므로, DATABASE_URL을 자체 Postgres로 지정할 수도 있다. 컨테이너가 시작될 때 마이그레이션이 자동으로 실행된다. 자세한 내용은 자체 호스팅 안내를 참고하면 된다. 호스팅 버전은 조직당 월 15달러다: ptd.danimoya.com.

보안 설정으로는 앱과 데이터베이스 사이의 TLS, SCRAM-SHA-256 인증, 데이터베이스의 HTTP/MCP 리스너 비활성화가 포함된다. HeliosDB-Nano 4.40 이상은 X25519MLKEM768 하이브리드 양자내성 키 교환을 지원하며, Node 24의 OpenSSL 3.5가 이를 협상한다. 서버 인증서는 공유 /tls 볼륨을 통해 고정되고 데이터베이스는 Compose 네트워크 밖에서 접근할 수 없다.

저장 데이터의 AES-256-GCM 행 암호화를 사용하려면 첫 실행 전에 DB_ENCRYPTION_KEY를 설정해야 한다. 외부 연동 비밀값은 PTD_SECRET_KEY를 사용해 AES-256-GCM으로 보호한다. 비밀번호는 bcrypt(cost 12), 에이전트 토큰은 scrypt 해시로 저장한다. 브라우저와 앱 사이의 TLS는 리버스 프록시에서 종료해야 하며, 호스팅 인스턴스는 HSTS를 적용한 nginx 뒤에서 운영된다.

텔레메트리는 기본적으로 꺼져 있고, Org → Data에서 사용자가 동의하면 활성화된다. 켜져 있을 때 전송되는 정보는 {installation_id, dashboard_version, heliosdb_version, timestamp}이며 주 1회 전송된다. IP 주소, 사용자 이름, 호스트 이름, 이름, 수량, 작업 데이터는 전송하지 않는다. 전송 전 페이지에서 JSON을 확인할 수 있다. 자세한 내용은 텔레메트리 전송 항목과 해제 방법에 나와 있다.

에이전트도 구성원으로 등록하며, 등록 후 MCP 서버와 REST API에 사용할 베어러 토큰을 받는다.

curl -X POST https://ptd.danimoya.com/api/agent/register \
 -H 'Content-Type: application/json' \
 -d '{"name":"Claude Code","inviteCode":"<from Org → Agents>"}'

이후 MCP 클라이언트는 https://ptd.danimoya.com/mcp에 Authorization: Bearer ptd_… 헤더를 사용해 연결한다. 에이전트 검색 주소는 /.well-known/ai-agent.json이다. 에이전트가 볼 수 있는 도구는 부여된 역할에 따라 달라지며, 같은 역할 제한이 MCP, REST, Slack 및 다른 어댑터에도 적용된다.

명령줄 클라이언트는 별도 의존성이 없는 Node 클라이언트로, 기본적으로 정렬된 표를 출력하고 --json으로 파이프 연결용 JSON을 출력한다. ptd run <action>으로 명령어에 별도 동사가 없는 작업도 실행할 수 있다.

npx @danimoya/ptd login --url https://ptd.danimoya.com # or: npm i -g @danimoya/ptd
ptd next # highest-priority task, with the arithmetic
ptd start SEC-3 && ptd stop --tokens 1200 --cost 0.04
ptd run task.totals --taskId=3 # any action, by name

전체 명령은 CLI 문서, 소스는 cli/에서 볼 수 있다. 개념과 역할은 개념 안내, 에이전트 설정과 비용 보고는 에이전트 안내, API는 API 문서, 연동은 연동 문서, 결제는 결제 문서, 보안은 보안 문서에서 확인할 수 있다. 전체 문서의 시작점은 docs/README.md다.

개발 환경에서는 DATABASE_URL과 JWT_SECRET을 설정한 뒤 마이그레이션, 시드 데이터 생성, 개발 서버 실행, 검사 및 테스트를 진행한다.

npm install
export DATABASE_URL=postgres://postgres:pw@127.0.0.1:5432/heliosdb JWT_SECRET=dev
npm run migrate && npm run seed # demo org with humans, agents, streams, tasks
npm run dev # API + Vite on :3001
npm run check && npm test
npm run docs # regenerate the action reference in docs/api.md

npm install --prefix cli && npm test --prefix cli # the CLI has its own package

docs/api.md의 액션 참조는 scripts/gen-docs.ts가 실시간 레지스트리에서 생성한다. 액션을 추가하거나 변경한 뒤 npm run docs를 실행하며, npm run docs -- --check는 문서가 최신 상태가 아니면 실패한다. PTD의 라이선스는 MIT다.