Okto Pulse
<div align="center">
<h3><em>AI 지원 개발을 위한 명세(Spec)-기반 프로젝트 관리.</em></h3>
</div>
<p align="center">
<strong>Okto Pulse는 아이디어, 개선 사항, 명세(specs), 작업(tasks), 테스트 및 버그를 AI 에이전트가 MCP를 통해 작동할 수 있는 관리되는 SDLC 보드로 변환합니다.</strong>
</p>
<p align="center">
<strong>AI와 함께 출시하고, 통제권을 유지하세요.</strong>
</p>
<p align="center">
<a href="https://pypi.org/project/okto-pulse/"><img src="https://img.shields.io/pypi/v/okto-pulse" alt="PyPI version"></a>
<a href="https://pypi.org/project/okto-pulse/"><img src="https://img.shields.io/pypi/pyversions/okto-pulse" alt="Python versions"></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-Elastic%202.0-blue" alt="License"></a>
<a href="https://github.com/OktoLabsAI/okto-pulse-core"><img src="https://img.shields.io/badge/core-okto--pulse--core-6f42c1" alt="Core repository"></a>
</p>
목차 (Table of Contents)
참고 문서 (Reference documents)
Okto Pulse란 무엇인가? (What is Okto Pulse?)
Okto Pulse는 AI 코딩 에이전트를 사용하는 팀이지만 여전히 추적성(traceability), 품질 게이트(quality gates) 및 지속적인 프로젝트 메모리(durable project memory)를 원하는 사용자를 위해 구축된 로컬 우선형 SDLC 워크벤치입니다.
에이전트가 프롬프트에서 코드로 바로 전송되는 대신, Okto Pulse는 작업 과정을 명시적으로 유지합니다:
Stories -> Ideation -> Refinement -> Spec -> Tasks / Tests / Bugs
모든 단계에는 구조화된 아티팩트(structured artifacts), 계보(lineage), 상태 전환(status transitions) 및 검증 규칙이 있습니다. 에이전트는 MCP 도구를 통해 이러한 아티팩트를 생성하고 업데이트할 수 있으며, 인간은 웹 UI에서 동일한 작업을 검사하고 방향을 설정할 수 있습니다.
Current 0.4.0 구현 표면:
| 표면 | 개수 |
|---|
| 거버넌스 게이트(Governance gates) | 핵심 거버넌스 패밀리 및 표준 게이트 계약을 참조하세요 |
| ... | |
커뮤니티 패키지는 FastMCP 호스트에서 전체 okto-pulse-core 명령어 카탈로그를 구현합니다. 이는 설치된 커뮤니티 런타임이 CLI, 프론트엔드 및 패키징 계층을 핵심 엔진과 분리하면서도 완전한 코어 도구 카탈로그에 노출됨을 의미합니다. MCP 개수는 구현 시점의 전송 중립적인(transport-neutral) 코어 카탈로그를 기준으로 측정됩니다. | |
| 커뮤니티는 추가적인 커뮤니티 전용 MCP 도구가 아닌 운영 리소스와 어댑터를 추가합니다. | |
시작하기 (Get Started)
1. 설치 (Install)
Okto Pulse는 Python 3.11 이상을 요구합니다.
[!NOTE]
Okto Pulse를 처음 실행할 때, all-MiniLM-L6-v2 문장 임베딩 모델(sentence-transformers model)이 Hugging Face 캐시에 다운로드됩니다. 이는 지식 그래프(Knowledge Graph)에서 의미론적 검색(semantic search) 기능을 제공합니다. 만약 모델을 다운로드할 수 없는 경우, 앱은 여전히 결정론적 스텁 모드(deterministic stub mode)로 시작하며 설정 보기(Settings view)에는 의미론적 검색이 비활성화되었다고 보고됩니다.
2. 작업 공간 초기화 (Initialize a workspace)
코딩 에이전트가 작동할 프로젝트 디렉토리 내에서 다음을 실행합니다:
이는 다음을 생성합니다:
~/.okto-pulse/ 아래의 로컬 데이터 디렉토리- 기본 보드 및 에이전트
- 에이전트를 로컬 MCP 서버에 연결하는 프로젝트별
.mcp.json 파일
3. 앱 시작 (Start the app)
기본 엔드포인트:
| 엔드포인트 | URL |
|---|
| 웹 UI + API | http://localhost:8100 |
| MCP 서버 | http://localhost:8101/mcp |
두 리스너는 하나의 Python 프로세스에서 실행됩니다. 이는 임베디드 그래프 데이터베이스를 단일 작성자(single writer)로 유지하면서도 독립적인 API/UI 및 MCP 포트를 노출합니다.
4. UI 열기
http://localhost:8100으로 이동하여 기본 보드를 선택하고 다음 중 하나로 시작합니다:
- Story: 주제별로 그룹화된 가벼운 사전 구상(pre-ideation) 컨텍스트가 필요할 때
- Ideation: 기능이나 문제가 이미 논의될 준비가 되었을 때
AI 코딩 에이전트 연결
대부분의 에이전트 도구는 동일한 디렉토리에서 실행될 때 생성된 .mcp.json을 자동으로 발견할 수 있습니다. Community는 로컬 REST 식별자를 의도적으로 사용자 전용으로 유지합니다. 인증된 에이전트 제출은 로컬에서 Core MCP 표면(surface)을 사용하며, SaaS 버전은 동일한 에디션 중립적 REST 계약에 에이전트 인식 AuthenticationPort를 주입할 수 있습니다. 어느 경로에서도 Community가 소스 코드를 획득하거나, 복제하거나, 탐색하거나, 프로브하거나, 검사하도록 만들지 않습니다. 외부 에이전트는 자체 환경에서 접근 권한과 기능을 확인하고 경계가 지정된 결과(bounded result)만 제출합니다.
| 에이전트 또는 도구 | 설정 방법 |
|---|
| Claude Code | .mcp.json 파일이 포함된 디렉토리에서 실행하세요. |
| ... | |
Codex (CLI) 버튼은 런타임 MCP 주소와 새로 공개된 API 키를 사용하여 codex mcp add okto-pulse --url "<Pulse MCP URL with agent key>" 명령을 복사합니다. 먼저 Codex CLI를 설치하세요. 키를 회전(rotating)한 후에는 새 명령어를 복사하여 실행하고, Codex 세션을 다시 시작해야 합니다. 이전 키는 작동하지 않습니다. 공개 한 번만 하는 키가 숨겨지면 구성 복사가 비활성화됩니다. 복사된 명령어는 비밀로 유지하세요. 이 명령어에는 키가 포함되어 있으며 셸 기록과 Codex의 구성에 저장될 수 있습니다. 이 명령어는 연결을 구성하며, 보드 접근은 여전히 Pulse에서 승인받아야 합니다. | |
| 공식 Codex MCP 문서를 참조하세요. | |
생성된 형태:
{
"mcpServers": {
"okto-pulse": {
...
MCP 포트를 변경했다면, 파일을 재생성하세요:
토큰 사용량
MCP를 통해 에이전트를 연결하는 것은 고정 컨텍스트 비용(도구 카탈로그)과 가변 비용(도구 응답)을 갖습니다. 응답 예측 기능인 summary, detail, full은 토큰 대비 디테일 수준을 조절할 수 있게 해줍니다.
→ 측정된 토큰 사용량 — 연결당 고정 비용, 온디맨드 리소스, 가변 응답 비용 및 대략적인 세션 프로필을 확인할 수 있습니다.
핵심 워크플로우 (Core Workflow)
Okto Pulse는 의도적으로 워크플로우 중심입니다. 각 단계는 서로 다른 질문에 답합니다.
| 단계 | 목적 |
|---|
| 스토리(Stories) | 주제별로 그룹화된 선택적 경량 사용자 스토리 입력으로, 하나 이상의 아이디어 도출 과정(ideations)에 피드를 제공할 수 있습니다. |
| ... | |
계보 그래프(lineage graph)는 스토리-아이디어 도출(story-to-ideation) 및 작업-테스트/버그(task-to-test/bug) 관계를 포함하여 이러한 관계들을 검사 가능하게 유지합니다.
거버넌스 게이트 (Governance Gates)
Okto Pulse는 상태 전환 시 실행되는 체크 기능을 통해 워크플로우를 보호합니다.
현재 플랫폼에는 17개의 명명된 거버넌스 게이트가 있습니다:
| 게이트군 | 게이트 |
|---|
| 리소스 준비 상태 (Resource readiness) | 리소스 준비 상태; 리소스-작업 커버리지 (resource-to-task coverage) |
| ... | |
- 명세(Specs)는 인수 기준(acceptance criteria), 기능 요구 사항(functional requirements), 비즈니스 규칙(business rules), API 계약(API contracts), 결정(decisions), 테스트 시나리오(test scenarios) 전반에 걸친 커버리지를 요구합니다.
- 부모 명세가 필요한 시나리오 커버리지를 갖추기 전까지는 작업(Tasks)이 시작될 수 없습니다.
완료(done)로 이동하는 작업은 완전성 및 드리프트 평가를 포함한 구조화된 결론을 필요로 합니다.- 미해결 인지적 통합 항목(cognitive-consolidation items)이 남아 있는 경우 완료 전환은 보류되며, 활성화된 아키텍처 경고는 명세나 카드가
완료에 도달하는 것을 차단합니다 (아키텍처 검토 결과 게이트/architecture-findings gate). 이 두 기능은 0.2.3 버전에서 '정의됨(defined)'에서 '강제됨(enforced)'으로 이동했습니다.
- 테스트 카드(Test cards)는 자동화, 통과 또는 실패로 표시되기 전에 증거를 요구합니다.
- 버그 카드(Bug cards)는 테스트 우선 워크플로우를 따르며 작업 및 관련 테스트 작업에 추적 가능하게 남아 있어야 합니다.
- 검증 게이트(Validation gates)는 명세나 작업이 완료된 것으로 간주되기 전에 독립적인 검토를 요구할 수 있습니다.
보드 설정은 추적성 모델을 제거하지 않으면서 팀이 임계값(thresholds)을 조정할 수 있게 합니다.
지식 그래프 (Knowledge Graph)
Okto Pulse는 영속적인 프로젝트 메모리를 위해 보드별 임베디드 지식 그래프(Knowledge Graph)를 유지합니다.
에이전트(Agents)는 이 그래프를 사용하여 다음 작업을 수행합니다:
- 관련 이전 결정 사항 찾기
- 모순 및 구식화된 컨텍스트 감지
- 이전 버그로부터의 교훈 재사용
- 보드 전반에 걸친 글로벌 디스커버리 컨텍스트 쿼리
- 사양(specs), 버그, 구현 결론을 검색 가능한 지식으로 통합
운영 상태(Operational health)는 다음을 통해 확인할 수 있습니다:
- 제품 내 지식 그래프(KG) 뷰
- MCP 건강 도구
- 데드레터 및 큐 메트릭
- 보드 설정 패널의 그래프 데이터베이스 런타임 설정
GET /health는 상수 시간(constant-time)의 활성 상태 엔드포인트입니다: 스토리지 스캔을 수행하지 않으며, 프로세스가 요청에 응답할 수 있는 동안 "healthy" 상태를 가진 HTTP 200을 반환합니다. 복구에는 애플리케이션 워크플로우 또는 검증된 백업/복원 절차를 사용해야 하며, 직접적인 SQL 수리는 지원되지 않습니다.
아키텍처
Okto Pulse는 두 개의 패키지로 배포됩니다: **okto-pulse-core**는 SDLC 도메인, 거버넌스 게이트(governance gates), 그리고 지식 그래프 계약(Knowledge Graph contracts)을 순수한 Protocol 심(seams)으로 소유합니다; okto-pulse(이 패키지)는 SQLite, Okto Grafx, 파일 시스템, 스케줄러, 원격 측정 상태(telemetry state), REST 앱 및 MCP 호스트와 같은 모든 구체적인 메커니즘을 소유합니다.
Core는 절대 Community를 임포트하지 않습니다. Community는 시작 시 포트를 채우며, 비어 있는 슬롯은 조용한 기본값으로 폴백(fallback)하는 대신 **닫힘 실패(fails closed)**합니다.
→ 전체 아키텍처 보기 — 의존성 소유자 매트릭스(AF-05/AF40), 등록 흐름, 어댑터 소스 맵, 그리고 각 어댑터 모듈이 구현하는 핵심 계약을 보여주는 포트 → 어댑터 매트릭스를 확인하세요.
CLI 참조
| Command | Description |
|---|
okto-pulse init | 로컬 데이터를 초기화하고 기본 보드를 시딩하며 .mcp.json 파일을 생성합니다. |
| ... | |
이전의 reset, verify-pipeline, 그리고 kg 명령어 그룹은 더 이상 허용되지 않으며, 해당 도움말/옵션도 마찬가지입니다. CLI는 데이터를 접근하기 전에 표준 알 수 없는 명령어 오류(exit 2)를 반환합니다. 로컬 관찰을 위해서는 status를 사용하십시오. 이는 KG 상태를 인증하거나 복구를 수행하지 않습니다. health observations 및 historical CLI corrections를 참조하십시오. | |
Docker로 실행하기
게시된 이미지 (Published image)
docker run -d --name okto-pulse \
-e HOST=0.0.0.0 \
-e MCP_HOST=0.0.0.0 \
...
그런 다음 http://localhost:8100을 엽니다. 첫 번째 시작 시에만 새로 생성된 부트스트랩 API 키가 출력됩니다. 저장된 키는 복구할 수 없으므로, 필요한 경우 UI/API를 통해 키를 재생성하십시오. 자동화의 경우 init --bootstrap-key-handoff를 사용하여 실행하고, 해당 명시적 파일을 api-key --handoff-file로 소비할 수 있습니다.
Compose
PyPI 기반 이미지를 원할 때는 프로덕션 compose 파일(docker-compose.prod.yml)을 사용하십시오:
docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -d
커뮤니티 패키지에서 작업하면서 형제 패키지인 okto-pulse-core 체크아웃과 함께 로컬 compose 파일을 사용할 때는 다음을 사용하십시오:
docker compose build
docker compose up -d
환경 변수 (Environment variables)
| 변수 | 기본값 | 용도 |
|---|
HOST | 127.0.0.1 | API/UI 바인드 호스트. 컨테이너에서는 0.0.0.0을 사용하십시오. |
Grafx의 경우, generation이 Pulse의 기본값입니다. Pulse는 관리되는 각 generation 디렉터리를 소유하며, 핸들(handles)이 닫힐 때만 복원/generation 교체를 수행하여 이 정책의 폐쇄된 라이프사이클을 충족합니다. 이는 Grafx의 캐노니컬 heap, catalog, index 및 WAL 이름에 대해서만 디스크립터 식별 증명(descriptor identity proofs)을 상각하며, control 및 unknown 이름은 엄격하게 유지됩니다. 이를 통해 페이지가 많은 그래프 읽기 작업에서 반복적인 네임스페이스 시스템 호출이 제거되지만, Grafx의 locking, WAL, OCC 또는 snapshot 규칙은 변경되지 않습니다. 다른 도구가 live generation을 수정하지 않는 일반적인 로컬 Pulse 런타임에 사용하십시오.
strict는 모든 캐시된 디스크립터 히트(descriptor hit) 뒤에 있는 물리적 식별자(physical identity)를 증명합니다. 외부 도구가 데이터베이스 디렉터리를 건드릴 수 있거나, 수동 유지보수 또는 불확실한 디렉터리 출처(provenance)를 가진 포렌식 작업, 혼합 신뢰성 호스트(mixed-trust hosts), 이름을 교체하는 live 파일 대체/복제 환경, 또는 지원되지 않는 공유 파일 시스템에서 이 정책을 선택하십시오. 이의 장점은 다음 물리적 작업 시 프로토콜 외 경로 대체(out-of-protocol path replacement)를 감지할 수 있다는 것이지만, 비용은 hot file에 대한 반복적인 네임스페이스/디스크립터 호출입니다. 반대로, generation은 명시적 무효화(directed invalidation), generation 전진(generation advance) 또는 재개방 시점까지 해당 지원되지 않는 변경 사항의 감지를 연기할 수 있습니다. 이 정책은 프로세스 로컬이며 영구 저장되지 않습니다. OCC, WAL, 내구성(durability) 또는 multiwriter/multireader 보장사항을 변경하지 않습니다. Pulse는 Grafx 풀당 하나의 정책을 고정하며, 관찰된 유효 모드(observed effective mode)가 구성과 다른 핸들은 거부합니다. 전체 화이트리스트와 전이 행렬(transition matrix)은 Okto Grafx의 docs/architecture/ST2_DESCRIPTOR_REVALIDATION.md에 명시되어 있습니다.