<p align="center">
<img src="https://raw.githubusercontent.com/ScriptedAlchemy/tracedecay/HEAD/crates/tracedecay-cli/src/resources/logo.png" alt="TraceDecay" width="300">
</p>
<h3 align="center">AI 코딩 에이전트를 위한 의미론적 코드 지능</h3>
<p align="center"><strong>토큰 감소 · 도구 호출 감소 · 기본적으로 로컬 작동</strong></p>
<p align="center">
<a href="https://github.com/ScriptedAlchemy/tracedecay/releases/latest"><img src="https://img.shields.io/github/v/release/ScriptedAlchemy/tracedecay" alt="GitHub release"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
<a href="https://www.rust-lang.org/"><img src="https://img.shields.io/badge/Rust-nightly-orange.svg" alt="Rust nightly"></a>
<img src="https://img.shields.io/badge/macOS-supported-blue.svg" alt="macOS">
<img src="https://img.shields.io/badge/Linux-supported-blue.svg" alt="Linux">
<img src="https://img.shields.io/badge/Windows-supported-blue.svg" alt="Windows">
</p>
TraceDecay는 사용자의 리포지토리에 대한 로컬 의미론적 그래프(semantic graph)를 구축합니다. AI 코딩 에이전트들은 이 그래프를 쿼리하여 심볼(symbols), 호출 관계(call relationships), 영향을 받는 호출자(affected callers), 문서(docs), 그리고 소스 스니펫(source snippets)을 얻습니다.
에이전트들은 반복적인 grep, glob 및 파일 읽기 대신, tracedecay_context, tracedecay_search, tracedecay_callers, 그리고 tracedecay_impact와 같은 MCP 도구를 사용합니다.
하이라이트
- discovery, call graphs, impact analysis, code health, test mapping, repository context, 그리고 anchored edits를 위한 Typed MCP 연산자들.
- lite/medium/full Cargo 기능 계층을 갖춘 Rust tree-sitter 추출기들;
Cargo.toml이 정확한 언어 권위(authority)이다.
- 지원되는 Claude Code, Codex, Cursor, Hermes, Kiro, Kimi Code, OpenCode, 그리고 Cline 계열 호스트를 위한 네이티브 통합.
rusqlite 런타임과 내장된 Grafeo 그래프 스토어를 통해 데몬(daemon)이 소유하는 로컬 저장소. 로컬 작업이 기본이며, 구성된 원격 소스 및 권위는 암묵적인 로컬 전용 보장보다는 명시적 정책을 따른다.- 연결된 git worktree 전반에 걸쳐 정확한 레포지토리(repository), worktree, ref, 커밋(commit), 그리고 생성 출처(provenance)를 가진 온디맨드 신선도 확인 기능.
- 프로젝트 전체의 사실 정보(facts), 세션, 그리고 손실 없는 LCM 기록은 브랜치 전반에 걸쳐 사용 가능하며, 과거 호스트 스크립트는 동일한 정제된 데몬 수집 경로를 통해 유입된다.
- 증거(evidence), 메모리, LCM 세션, 절감액, 그리고 비용 분석을 위한 로컬 대시보드.
설치 (Install)
curl -fsSL https://raw.githubusercontent.com/ScriptedAlchemy/tracedecay/master/install.sh | bash
...
설치 프로그램은 기본적으로 ~/.local/bin을 사용한다. 다른 디렉토리를 선택하려면 TRACEDECAY_INSTALL_DIR를 설정하라. 이 프로그램은 gh attestation verify를 사용하여 아카이브의 빌드 출처 증명(build-provenance attestation)을 확인하므로, GitHub CLI에 로그인해야 한다. gh가 없으면 체크섬만 허용하는 설치(TRACEDECAY_INSTALL_UNATTESTED=1)를 수락하지 않는 한 거부된다.
tracedecay upgrade는 동일한 증명을 자체적으로 확인한다. 사용자 가이드를 참조하라. 미리 빌드된 아카이브는 최신 릴리스에서 이용 가능하다.
최종 V2 저장소 모델 (Final V2 storage model)
tracedecay-graph-db는 유일한 Grafeo 의존성 경계입니다. 최종 V2는 오직 그 정확하게 영속화된 형태만을 허용합니다: 호환되지 않는 스토어는 ResetRequired를 반환하며, 변환이 아닌 명시적인 재설정 또는 재생성을 요구합니다. V2 작동 모델을 참조하십시오.
Quick start
cd /path/to/your/project
tracedecay daemon install-service
tracedecay init
...
tracedecay init은 프로젝트를 등록하고 첫 번째 코드 생성을 요청합니다. 이 요청이 수락되면 유형화된 준비되지 않음(typed not-ready) 영수증을 반환하며, 인덱싱은 백그라운드에서 계속됩니다. 그 직후에 실행되는 tracedecay status는 여전히 종료 코드 0과 함께 project_open.state=converging 및 graph_statistics.state=unavailable를 표시할 수 있습니다. 이는 사용 가능한 프로젝트가 아니라 유형화된 준비되지 않음 상태의 읽기 값입니다. 첫 번째 생성이 준비될 때까지 블록하려면 tracedecay init --wait을 전달하거나, graph_statistics.state가 사용할 수 있을 때까지 status를 폴링하십시오. --wait은 데몬이 인덱싱, 복원 또는 소스 검증 작업을 진행 중이라고 보고하는 동안 유지됩니다. 데몬이 2분 동안 생성에 대한 작업이 없다고 보고하면 종료 코드 75를 반환하며, 수렴(convergence)이 보류되거나 코드-인덱스 마운트가 실패하면 즉시 실패합니다.
데몬이 먼저 작동해야 합니다. tracedecay init은 데몬 소유의 코드-인덱스 스케줄러를 통해 중개되므로, 실행 중인 데몬 없이는 아무것도 쓰기 전에 거부됩니다:
Error: project route error (code_index_scheduler_unavailable): project initialization requires the daemon-owned code-index scheduler; start the daemon and retry
systemd 사용자 버스가 없는 헤드리스 Linux 환경에서는 한 터미널에서 tracedecay daemon run을 실행하고, 다른 터미널에서 위의 명령들을 사용하면서 계속 실행 상태로 유지하십시오. tracedecay status는 데몬을 읽어올 뿐 시작하지 않습니다. 라이프사이클 명령어는 사용자 가이드를 참조하십시오.
tracedecay install은 지원되는 에이전트를 자동으로 감지합니다. 특정 호스트를 대상으로 하려면:
tracedecay install --agent claude
tracedecay install --agent codex
tracedecay install --agent cursor
...
프로젝트 로컬 설정 (Project-local setup):
tracedecay install --local --agent cursor
tracedecay install --local --agent codex
tracedecay install --local --agent devin
설정 후에는 에이전트를 재시작하여 해당 호스트를 위해 작성된 MCP 서버, 플러그인, 훅(hooks) 또는 규칙을 로드하도록 해야 합니다.
Codex는 최초 설치 시 자체적으로 codex plugin add tracedecay@personal을 실행합니다. /hooks를 사용하여 Codex 내부의 새로운 명령어 훅(command hooks)을 신뢰한 다음, 설치된 캐시가 로드되도록 새 세션을 시작하십시오.
일반 명령어 (Common Commands)
tracedecay daemon install-service
tracedecay daemon run
tracedecay init [path]
...
모든 MCP 도구는 셸에서 tracedecay tool <이름> 형식으로 접근할 수 있으며, 개별 도구마다 별도의 하위 명령어가 없습니다. 그룹화된 목록은 tracedecay tool을 실행하고, 특정 도구의 매개변수는 tracedecay tool <이름> --help를 사용하십시오.
MCP 서버는 일반적인 코딩 워크플로우를 중심으로 그룹화된 도구들을 노출합니다:
- 발견/탐색 (Discovery):
tracedecay_context, tracedecay_search, tracedecay_source_outline, tracedecay_files
- 그래프 순회 (Graph traversal):
tracedecay_callers, tracedecay_callees, tracedecay_impact, tracedecay_affected
- 코드 상태/건강도 (Code health):
tracedecay_complexity, tracedecay_dead_code, tracedecay_unmounted_files, tracedecay_coupling, tracedecay_test_risk
- Git 워크플로우 (Git workflow):
tracedecay_pr_context, tracedecay_commit_context, tracedecay_diff_context, tracedecay_git_diff, tracedecay_changelog, tracedecay_test_map
- 편집 (Editing):
tracedecay_str_replace, tracedecay_multi_str_replace, tracedecay_insert_at, tracedecay_ast_grep_rewrite
- 메모리 (Memory): 정확한
tracedecay_fact_store_add|search|probe|related|reason|contradict|get|update|remove|list 경로, 그리고 tracedecay_fact_feedback, tracedecay_memory_status
대부분의 읽기 도구(read tools)는 병렬로 호출해도 안전합니다. 편집 도구(Edit tools)는 단일 파일에 고정되며, 작성 후 재색인화됩니다.
tracedecay_pr_context를 사용하여 PR 작업을 시작합니다. 이 간결한 브리핑은 PR 설명 및 토론, 보존된 CI 관찰 기록(retained CI observations), 변경 맵(change map), 그리고 우선순위가 지정된 소스 진입점들을 결합합니다. 기본값은 보존된 GitHub 증거를 읽으며, refresh_github: true로 설정하여 구성된 소유자(owner)를 통해 새로 고침을 요청할 수 있습니다. 제한적이거나 사용할 수 없는 새로 고침의 경우 명시적인 보존 폴백(retained fallback)이 남습니다. PR 번호는 이 체크아웃의 증거를 선택하며, 임의의 PR을 가져오지는 않습니다.
기록된 리비전(revision)에서 진입점을 읽습니다. source_lines는 전체 커밋 ID(commit ID), 저장소 상대 경로의 file, 그리고 포함 범위가 지정된 start_line/end_line을 허용하며, 다음 전체 라인 창은 next_line을 따릅니다. 현재 색인화된 소스 및 그래프 탐색에는 반환된 node_id 값을 사용하고, 페이지 처리된 변경 심볼 보고서(paginated changed-symbol report)를 위해서는 view: "symbols"를 사용합니다. 소스 커버리지(Source coverage)는 명시적으로 유지되며, budget_tokens는 근사치이고, 보존된 CI가 병합 준비 상태(merge readiness)를 확립하지는 않습니다.
보류 중인 커밋(pending commit)의 경우, staged_only: true를 사용한 commit_context는 실제 인덱스 블롭(index blobs)을 읽습니다. 기본값은 추적되지 않은 파일(untracked files)을 포함하여 HEAD와 현재 작업 트리(working-tree) 내용을 비교합니다. 작업 트리에서 되돌려진 스테이징된 편집 내용은 해당 기본 보기에서는 순 변화가 없습니다. diff_context는 패치(patch)가 변경하지 않은 선언(declarations)을 포함하여 제공된 파일의 모든 색인화된 심볼에 대한 잠재적 영향을 알려줍니다.
인덱스 신선도 (Index Freshness)
데몬(daemon)은 최신성(freshness)과 백그라운드 수렴(background convergence)을 담당합니다. Hooks, MCP, LSP 및 작업 영역 이벤트는 경계가 지정되고 내용이 없는 힌트(hint)를 제출하며, 데몬은 정확한 저장소/작업 트리/참조(ref)/커밋 식별자를 해결하고 스냅샷을 캡처한 다음 불변의 생성물(immutable generation)을 게시합니다. 쿼리는 새로운 생성물이 준비되는 동안 해당 생성물과 유형화된 warming/refresh_required/partial/unavailable 커버리지를 보고하며, 절대로 숨겨진 동기화(sync)를 실행하거나 조용히 조상(ancestor) 버전을 사용하지 않습니다. 명시적인 tracedecay sync는 진단 또는 오프라인 워크플로우를 위한 관리적 새로고침 요청으로 남아 있습니다.
연결된 Git 작업 트리(Linked git worktrees)는 저장소 공통 디렉터리를 통해 하나의 등록된 프로젝트 권한(project authority)을 공유합니다. 어느 체크아웃에서든 한 번 초기화하고, TraceDecay 스토어를 다른 작업 트리에 복사하지 마십시오. 쿼리와 비교는 정확한 작업 트리/참조/커밋 생성물을 선택하며, 해당 스냅샷이 준비되지 않았을 때 유형화된 stale(오래됨), indexing(색인 중), partial(부분적) 또는 unavailable(사용 불가) 상태를 보고합니다. 브랜치와 작업 트리는 별도의 데이터베이스나 사실 저장소(fact store)를 생성하지 않습니다.
브랜치 선택, 출처(provenance), 복구 동작에 대해서는 docs/V2-OPERATING-MODEL.md를 참조하십시오.
대시보드 (Dashboard)
tracedecay dashboard --path /path/to/enrolled/repo
tracedecay dashboard --path /path/to/enrolled/repo --port 8080
tracedecay dashboard --path /path/to/enrolled/repo --port 0 --open
대시보드는 하나의 실행 프로젝트에 바인딩됩니다: --path 또는 현재 디렉터리입니다. $HOME이나 다른 임베디드 루트에서 실행을 시도하면 거부되며, --path를 전달하도록 안내합니다. 코드 검색은 오직 해당 바인딩된 프로젝트만을 다룹니다. 다른 등록된 저장소에 대해 문의할 경우, 성공적인 빈 목록 대신 유형화된 wrong_project 또는 empty_scope 상태가 반환됩니다. 대시보드에는 그래프 탐색, 프로젝트 메모리, LCM 세션 검색, 토큰 절약 및 비용 보기 기능이 포함되어 있습니다. docs/dashboard.md를 참조하십시오.
개인 정보 보호 (Privacy)
핵심 인덱싱(Core indexing), 그래프 쿼리(graph queries), MCP 도구(MCP tools), 메모리(memory), 대시보드 데이터(dashboard data)는 기본적으로 로컬 데몬 소유 권한을 사용합니다. 이 기본 설정이 모든 명령이 오프라인이라는 것을 의미하지는 않습니다. 구성된 원격 소스 및 권한은 해당 원격 정책에 따라 승인되고, 정제되었으며, 분류된 기록만을 교환할 수 있습니다.
네트워크 기능을 갖춘 효과(effects)는 핵심 검색(core retrieval)과 분리되어 있습니다:
- GitHub 릴리스 확인 및 업데이트: GitHub 릴리스 엔드포인트에 연결합니다. 명시적으로 구성된 비공개 GitHub 검토 소스는 운영 체제 키링(operating-system keyring)의 읽기 전용 자격 증명(read-only credential)을 사용할 수 있습니다. 누락되거나, 모호하거나, 쓰기 권한이 있거나, 검증할 수 없는 자격 증명은 닫힘 실패(fail closed) 처리됩니다.
- 시맨틱 모델(Semantic models): 시맨틱 자동 다운로드(semantic auto-download)가 활성화되면, TraceDecay는 누락된 리비전 고정 아티팩트(revision-pinned artifacts)를 Hugging Face 호스트에서 다운로드하고 출판 전에 해당 카탈로그 고정 길이 및 SHA-256 다이제스트(SHA-256 digests)를 검증할 수 있습니다.
- 구성된 원격 권한(Configured remote authority): 인증되고 정책에 의해 승인된 피어는 원격 검색, 복제(replication), 백업, 복원(restore) 또는 장애 조치(failover)를 수행할 수 있습니다. 이 경로는
unavailable, denied, 또는 stale-peer 상태의 유형화된 값으로 닫힘 실패(fails closed) 처리됩니다.
로컬 전용 읽기(Local-only reads)에는 tracedecay cost가 포함됩니다: 이는 네트워크 새로 고침이나 환경 기반 가격 책정 캐시 없이 불변의 네이티브 사용 관측치(immutable native usage observations)와 번들된 모든 공급자 가격표를 사용합니다. 알려지지 않거나 사용할 수 없는 가격 증거는 0으로 조용히 설정되는 대신 유형화된 상태로 유지됩니다.
이러한 서비스는 요청 페이로드 외에도 연결의 소스 주소와 같은 일반적인 전송 메타데이터를 수신합니다. 명령이 아웃바운드 연결을 할 수 없어야 하는 경우 네트워크 정책이나 방화벽을 사용하십시오. 거부(denial), 시간 초과(timeout) 또는 사용할 수 없는 원격 서비스는 해당 상태로 계속 표시되어야 합니다. 이는 최신 릴리스나 현재 가격 책정의 증거가 아닙니다. TraceDecay는 더 이상 전 세계 토큰 카운터를 가지고 있지 않습니다: 토큰 절약 및 비용은 로컬에 유지됩니다. 전체 아웃바운드 액세스 및 자격 증명 경계(credential boundary)는 Security를 참조하십시오.
문제 해결 (Troubleshooting)
tracedecay doctor
tracedecay status --json
