Give your agent a proper IDE and OS. The sensorimotor cortex for coding agents (OpenCode + Pi), part of CortexKit: symbol-aware edits, semantic search, code health, fast grep/glob, bash compression, background tasks, PTY.

AFT – 코드 에이전트를 위한 감각운동 피질

무엇인가요 – AFT (Agent File Tools)는 LLM 기반 코드 에이전트에 실제 IDE와 유사한 코드베이스 인식과 OS와 유사한 실행 계층을 제공하는 Rust 기반 코어입니다. 에이전트(예: OpenCode, Pi, oh-my-pi 등)와 호스트 파일 시스템 사이에 위치하며, 원시적인 read/write/grep 호출 대신 고수준의 심볼 인식 도구(aft_outline, aft_zoom, aft_edit, aft_bash, ...)를 노출합니다.

핵심 아이디어 (뇌의 은유)

영역	역할	예시 도구
감각 피질	코드 구조, 의미, 관계 인식	`aft_outline`, `aft_zoom`, `aft_search`, `aft_callgraph`, `aft_inspect`
운동 피질	정밀한 구문 분석 편집 및 리팩터링 수행	`aft_edit`, `aft_write`, `aft_apply_patch`, `aft_import`, `ast_grep_*`
뇌간	장시간 실행 프로세스 유지, 출력 압축, 되돌리기/복원 제공	`aft_bash`, 백그라운드 작업, PTY 세션, `aft_safety`

지원되는 에이전트 "하네스"

하네스	AFT 통합 방식
OpenCode	네이티브 어댑터 (`@cortexkit/aft-opencode`)가 내장된 `read`, `write`, `edit`, `apply_patch`를 AFT 기반 버전으로 대체하고 `aft_` 도구 패밀리를 추가합니다.
Pi	네이티브 확장 (`@cortexkit/aft-pi`)가 `read`, `write`, `edit`, `grep`를 대체하고 `aft_` 도구를 추가합니다.
OMP (oh-my-pi)	Pi 플러그인을 통해 지원되며, 기본적으로 최상위 레벨에 도구를 등록하고, 선택적 "host_default" 표시 모드를 제공합니다.

주목할 만한 기능

구조 인식 인식 – aft_outline은 함수, 클래스, 타입 등 모든 심볼을 종류, 가시성, 라인 범위, 중첩된 멤버와 함께 반환합니다. aft_zoom은 단일 심볼에 깊이 들어가 콜 그래프 정보를 포함할 수 있습니다.
하이브리드 의미적 + 어휘 검색 – aft_search는 트라이그램 인덱스에 더해 선택적 임베딩 백엔드(OpenAI 호환 또는 Ollama)를 사용해 의미에 따라 코드를 찾습니다.
심볼 수준 편집 – aft_edit은 이름이 지정된 함수를 직접 교체하거나, 흐릿한 검색/치환, 다중 파일 트랜잭션 편집을 수행할 수 있습니다. 모든 변경 사항은 쓰기 전에 구문 분석, 포맷팅, 백업됩니다.
자동 임포트 관리 – aft_import는 언어 인식 기반으로 임포트를 추가, 제거, 정리합니다.
AST 기반 구조적 치환 – ast_grep_search / ast_grep_replace를 사용해 tree-sitter AST를 사용해 코드 패턴을 매칭할 수 있습니다.
강력한 bash 실행 – aft_bash는 출력 압축, 권한 스캔, 일반 유틸리티 자동 재작성(cat → read, grep → grep tool)과 함께 쉘 명령어를 실행합니다. 백그라운드 작업은 에이전트 재시작 후에도 유지됩니다.
되돌리기 / 체크포인트 – 모든 편집은 파일별 되돌리기 스택에 저장됩니다. 에이전트는 이름이 지정된 체크포인트를 만들고 안전하게 롤백할 수 있습니다.
언어 커버리지 – 30개 이상의 언어(TS/JS, Python, Rust, Go, C/C++, Java, Kotlin, Swift 등)의 tree-sitter 파서를 통해 아웃라인, 편집, AST, 의미 기능이 가능합니다.
지속적 인덱스 및 LSP – 트라이그램 검색, 의미 임베딩 인덱스, 내장된 LSP 클라이언트는 프로젝트 루트당 장시간 실행되는 aft 프로세스에서 유지됩니다.

빠른 시작 (원라인)

npx @cortexkit/aft@latest setup

이 명령어는 설치된 하네스를 감지하고 AFT 도구를 등록하며 aft 바이너리가 사용 가능하도록 보장합니다. 특정 하네스를 지정하려면 --harness opencode|pi|omp를 사용할 수 있습니다.

설치 세부 정보

Rust crate – crates.io의 agent-file-tools (핵심 바이너리).
NPM 패키지 – @cortexkit/aft (CLI), @cortexkit/aft-opencode, @cortexkit/aft-pi (하네스 어댑터).
바이너리 배포 – CLI는 처음 사용 시 플랫폼에 맞는 사전 빌드된 바이너리를 다운로드하며, 필요 시 cargo install 또는 GitHub 릴리스로 대체됩니다.
설정 – 선택적 aft.jsonc (사용자 수준 ~/.config/cortexkit/aft.jsonc 또는 프로젝트 수준 <repo>/.cortexkit/aft.jsonc). enabled: false로 설정하면 AFT를 비활성화하거나 도구 표면, 의미 백엔드, LSP 서버, 압축 등을 조정할 수 있습니다.
제거 – npx @cortexkit/aft@latest doctor를 실행해 남아 있는 항목을 확인한 후, 하네스 설정에서 플러그인 항목을 수동으로 제거하고 ~/.local/share/cortexkit/aft/ 데이터 디렉터리를 삭제합니다. AFT 자체에는 전용 제거 명령어가 없습니다.

개발 및 기여

TypeScript 어댑터용 Bun 워크스페이스와 Rust 코어용 Cargo 워크스페이스를 포함한 모노레포.

빌드 단계:

bun install            # JS 종속성 설치
cargo build --release  # Rust 바이너리 컴파일
bun run build          # TS 플러그인 빌드

테스트: bun run test (TS) 및 cargo test (Rust).
포맷팅: bun run lint (Biome) 및 cargo fmt.
기여는 "디자인 우선" 워크플로우를 따릅니다: 이슈를 열고 design-approved 레이블을 받은 후 PR을 제출합니다.

라이선스

MIT – 개인 및 상업적 사용에 자유롭게 사용 가능.

요약하면 – AFT는 LLM 기반 코드 에이전트에게 언어 인식 가능한 완전한 기능의 IDE와 가벼운 OS 계층을 제공하여, 에이전트가 코드를 읽고 편집하거나 실행할 때 토큰 사용량을 크게 줄이고 신뢰성을 높입니다.

cortexkit/aft