LoopX 사용법 2026: 장기 실행 AI 에이전트 상태 관리 가이드

LoopX 사용법을 찾는 사람은 대개 Codex나 Claude Code에 며칠씩 이어지는 개발, 리서치, benchmark를 맡기려는 경우가 많습니다. 세션이 바뀌면 목표와 todo가 흐려집니다. 여러 agent가 교대로 일할 때는 누가 무엇을 맡았는지 추적하기도 어렵습니다.

LoopX는 이때 objective, gate, todo, evidence, quota를 로컬에 보존하는 오픈소스 control plane입니다. agent를 대신 실행하는 framework는 아닙니다. 각 실행 사이에 남아야 할 상태를 관리합니다. 이 글에서는 v0.4.3을 설치하고 기존 프로젝트를 연결한 다음, 첫 장기 goal의 상태를 확인하는 과정까지 다룹니다.

검증일: 2026-08-09 02:35 UTC. GitHub API, 공식 README, pyproject.toml, v0.4.3 release note를 대조했습니다.

최종 결과물: LoopX로 만드는 장기 실행 agent 작업판

설정을 마치면 프로젝트 root에서 다음 명령으로 현재 작업 상태를 읽을 수 있습니다.

loopx status

정상 연결된 프로젝트에서는 다음 정보가 한 화면에 나옵니다.

• 장기 작업의 objective와 허용된 scope
• 사람이 결정해야 하는 구체적인 user gate
• agent가 이어서 처리할 todo와 현재 owner
• 이전 turn에서 남긴 evidence와 validation 결과
• 다음 turn을 실행할 수 있는지 판단하는 quota

기본 흐름은 단순합니다. LoopX가 상태를 읽다가 사람의 판단이 필요하면 질문을 남기고 기다립니다. 안전하게 이어갈 todo와 quota가 있으면 Codex나 Claude Code가 제한된 한 번의 작업을 실행합니다. 작업이 끝난 뒤에는 결과와 근거, 다음 todo를 기록하고 quota를 다시 확인합니다.

LoopX의 대시보드나 Kanban은 이 상태를 읽어 보여주는 화면입니다. 실제 source of truth는 프로젝트 로컬에 저장된 LoopX state입니다.

원클릭 설치: 가장 짧은 LoopX 설치 경로

공식 quick start가 요구하는 환경은 Python 3.11 이상, curl, tar, macOS 또는 Linux shell입니다. 일반 설치에는 Git이 필요하지 않습니다. Git은 contributor clone이나 canary workflow에서만 사용합니다.

공식 README의 가장 짧은 설치 명령은 다음과 같습니다.

curl -fsSL https://huangruiteng.github.io/loopx/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctor

원격 script를 바로 shell에 전달하기 부담스럽다면 파일로 내려받아 내용을 확인한 뒤 실행하세요.

curl -fsSL https://huangruiteng.github.io/loopx/install.sh \
  -o /tmp/loopx-install.sh
less /tmp/loopx-install.sh
bash /tmp/loopx-install.sh

2026년 8월 9일 확인 기준으로 최신 release는 v0.4.3입니다. pyproject.toml에는 runtime dependency가 비어 있으며, 표준 라이브러리 밖의 package를 요구하지 않습니다.

1단계: 설치 상태와 버전을 먼저 확인하기

설치가 끝나면 version과 환경 진단을 확인합니다.

loopx --version
loopx doctor

loopx doctor는 CLI와 로컬 설정이 정상인지 확인하는 출발점입니다. 여기서 오류가 남는다면 goal을 만들거나 heartbeat를 붙이기 전에 원인부터 해결하는 것이 좋습니다.

공식 release note는 v0.4.3에 breaking change가 없고 persisted state migration도 필요하지 않다고 안내합니다. 기존 설치를 update할 때도 먼저 --check 결과를 읽은 뒤 실행합니다.

loopx update --check --ref stable
loopx update --execute --ref stable
loopx doctor

2단계: 기존 프로젝트를 LoopX에 연결하기

관리할 프로젝트 root로 이동한 뒤 connect를 실행합니다.

cd /path/to/your-project
loopx connect
loopx status

LoopX는 기존 state가 있다면 재사용하고 덮어쓰지 않아야 합니다. connect 직후 status를 실행해 active objective와 gate, 다음 todo가 예상대로 보이는지 확인합니다.

연결이 정상이라면 .loopx/registry.json과 active goal projection이 만들어집니다. runtime이 바뀌어도 목표 상태를 이어 가는 기준입니다.

3단계: 첫 장기 goal 만들기

connect가 state를 찾지 못하면 guided start로 goal을 만듭니다.

loopx start-goal --guided \
  --project . \
  --goal-text "장기 실행할 목표를 구체적으로 입력"

goal에는 결과와 범위를 분명히 적어야 합니다. “프로젝트를 개선한다”보다 “로그 수집 pipeline의 누락 원인을 찾고 재현 test와 수정 PR을 만든다”처럼 완료 조건을 적는 쪽이 낫습니다.

처음부터 production write나 publish 권한을 넣지 마세요. 삭제, 배포, 공개처럼 되돌리기 어려운 작업은 user gate로 분리하고, agent가 질문을 남긴 뒤 기다리게 해야 합니다.

4단계: todo, gate, evidence 흐름 확인하기

LoopX에서 agent가 실제로 일하기 전후에 쓰는 핵심 명령은 다음 다섯 개입니다.

자동 turn은 항상 quota should-run부터 확인해야 합니다. preflight 실패, dry-run, 조용한 skip은 slot을 소비하지 않습니다. spend-slot은 검증된 writeback이 끝난 뒤에만 기록하는 것이 공식 운영 원칙입니다.

여러 agent가 함께 작업할 때는 todo claim이 특히 중요합니다. claim과 lease가 보이지 않으면 같은 파일을 동시에 수정하거나 이미 끝난 조사를 반복하기 쉽습니다. 결과를 넘길 때도 단순한 “완료”로 끝내지 마세요. 실행한 command, test 결과, 관련 issue나 PR을 evidence로 남겨야 다음 agent가 다시 검증할 수 있습니다.

5단계: Codex와 Claude Code에 연결하기

Codex App이나 Codex CLI에서는 agent에게 현재 프로젝트를 LoopX에 연결하고 loopx doctor를 실행하도록 요청합니다. 연결이 끝나면 $loopx <complex task>를 사용하거나 /skills에서 loopx를 선택합니다.

Codex App over SSH는 다음 onboarding 명령을 제공합니다.

loopx agent-onboard \
  --agent-type codex-app-ssh \
  --project .

Claude Code는 opt-in adapter를 설치한 뒤 /loopx <task>로 목표를 만들고 /loop를 실행하는 흐름입니다. Cursor, OpenCode, Pi, shell agent, custom runner에서도 LoopX CLI를 직접 호출할 수 있습니다.

provider-neutral이라는 설명은 이 구조를 가리킵니다. 실제 계획과 도구 사용은 agent runtime이 담당합니다. LoopX는 runtime 밖에서 objective, gate, todo, evidence, quota를 유지합니다.

병렬 agent를 workspace 단위로 분리하려면 Orca 사용법 2026을 같이 참고하세요. plan, implement, review 흐름을 나누는 방식은 Compound Engineering 사용법에 정리돼 있습니다.

6단계: 자동 실행 전에 안전장치 정하기

heartbeat나 scheduler를 연결하기 전에는 다음 항목을 먼저 확인합니다.

• .loopx/, .codex/goals/, .local/을 Git ignore 대상에 넣습니다.
• credentials, private log, raw benchmark trace를 공개 저장소에 commit하지 않습니다.
• production write, publish, 삭제는 구체적인 user gate 뒤에 둡니다.
• agent가 처리할 수 있는 scope와 protected file을 명시합니다.
• quota와 stop condition을 수동으로 한 번 검증합니다.
• todo update에는 command output, test 결과, 관련 PR 같은 evidence를 남깁니다.

LoopX는 dangerous permission을 대신 승인하지 않습니다. autonomous production controller도 아닙니다. 사용자가 credentials와 destructive action의 최종 권한을 계속 가져야 합니다.

긴 작업을 끝까지 이어 가는 prompt 운영 방식은 fablize 사용법과 비교해 볼 만합니다. fablize가 한 agent의 실행 지속성을 보조한다면 LoopX는 여러 turn과 agent 사이의 상태를 관리하는 쪽에 가깝습니다.

7단계: 검토 자료와 운영 상태 확인하기

사용자가 진행 상황을 검토할 때는 review-packet을 사용할 수 있습니다.

loopx review-packet

이 명령은 결정, evidence, validation, 아직 풀리지 않은 gate를 검토용으로 묶습니다. 일상 점검에서는 다음 명령을 함께 확인합니다.

loopx status
loopx history --goal-id your-project-goal
loopx quota should-run --goal-id your-project-goal

v0.4.3은 turn result와 quota packet을 같은 EffectTurn 관점으로 다루는 effect interpreter 구조를 구체화했습니다. execution_mode를 data로 표현하고 ordered effect program 형태를 추가했으며, bilingual Dev Book의 Control-Plane Course도 독립된 학습 경로로 정리했습니다.

문제 해결

loopx: command not found가 나온다

installer가 $HOME/.local/bin에 CLI를 설치했지만 현재 shell의 PATH에 반영되지 않았을 가능성이 큽니다.

export PATH="$HOME/.local/bin:$PATH"
loopx --version

계속 사용할 shell profile에도 같은 경로를 추가한 뒤 새 terminal에서 다시 확인합니다.

connect가 state를 찾지 못한다

새 프로젝트라면 오류가 아니라 초기화가 필요한 상태일 수 있습니다. 프로젝트 root가 맞는지 확인하고 guided start를 실행합니다.

loopx start-goal --guided \
  --project . \
  --goal-text "장기 실행할 목표를 구체적으로 입력"

다음 turn이 실행되지 않는다

먼저 quota와 gate를 확인합니다.

loopx status
loopx quota should-run

user gate가 남아 있거나 quota가 turn을 허용하지 않는다면 scheduler를 강제로 우회하지 마세요. 질문에 답하고 stop condition과 slot 사용 내역을 확인해야 합니다.

여러 agent가 같은 todo를 처리한다

작업 전 loopx todo claim을 사용하고 claim과 lease가 상태에 남았는지 확인합니다. 작업 뒤에는 loopx todo update로 validation과 handoff를 기록해야 다음 agent가 같은 일을 반복하지 않습니다.

공개 정보: v0.4.3 기준으로 확인한 값

조회 시점은 2026-08-09 02:35 UTC입니다.

GitHub Release에는 wheel, source archive, SHA256SUMS가 올라와 있습니다. v0.4.3 release note에는 PyPI Trusted Publishing이 비활성 상태라고 적혀 있습니다. 이름이 같은 비공식 package를 임의로 설치하지 말고 공식 installer나 GitHub Release 경로를 확인하세요.

요약: LoopX 사용법을 적용할 때의 기준

LoopX는 긴 작업의 prompt를 대신 써 주지 않습니다. objective, todo, gate, evidence, quota를 agent runtime 밖에 남겨 여러 세션과 agent가 같은 상태를 이어받도록 돕는 control plane입니다.

짧은 일회성 작업이라면 설정 비용이 더 크게 느껴집니다. 며칠 동안 이어지는 개발, issue와 PR loop, 반복 monitor, multi-agent handoff에서는 현재 상태와 다음 행동을 한곳에서 확인할 수 있습니다.

처음에는 작은 프로젝트에서 doctor, connect, status, 수동 quota 확인까지만 검증하세요. 이 흐름이 안정된 뒤 heartbeat와 scheduler를 붙이는 순서가 안전합니다.

FAQ

LoopX가 Codex나 Claude Code를 대신 실행하나요?

아닙니다. 계획과 도구 실행은 Codex나 Claude Code 같은 agent runtime이 담당합니다. LoopX는 objective, gate, todo, evidence, quota를 관리합니다.

Windows에서도 설치할 수 있나요?

공식 quick start의 지원 환경은 macOS 또는 Linux shell입니다. Windows에서는 WSL 같은 Linux 환경을 검토할 수 있지만 공식 요구사항 밖의 경로이므로 loopx doctor와 state path를 따로 확인해야 합니다.

기존 프로젝트 state를 덮어쓰나요?

공식 README는 기존 state를 재사용하고 덮어쓰지 않아야 한다고 안내합니다. connect 뒤 status와 .loopx/registry.json을 확인하고, 중요한 프로젝트라면 branch나 backup을 먼저 준비하세요.

production 자동화에 바로 사용해도 되나요?

공식 문서는 LoopX가 autonomous production controller가 아니라고 밝힙니다. credentials 부여, destructive action, publish, production write의 최종 승인은 사람이 맡아야 합니다.

공식 출처

• LoopX GitHub 저장소
• LoopX v0.4.3 release note
• LoopX 공식 문서
• LoopX pyproject.toml
• LoopX LICENSE