시작하기

준비물

• bun으로 실행 가능한 Bun 설치.
• gjc가 작업할 Git 저장소.
• 권장 gjc --tmux 경험을 쓸 경우 tmux.
• 접근 가능한 모델 provider 하나 이상.

OS와 셸 메모는 추천 환경을 참고하세요.

설치

Gajae-Code는 npm 레지스트리에 gajae-code로 배포됩니다. 권장 런타임은 Bun입니다.

bun install -g gajae-code

gjc 바이너리가 설치됩니다. 스코프 패키지 @gajae-code/coding-agent로도 받을 수 있습니다.

실행

권장하는 tmux 기반 환경으로 시작합니다.

gjc --tmux

gjc만 실행하면 tmux 세션을 만들거나 붙지 않고 바로 켜집니다.

gjc

브랜치 단위로 더 안전하게 작업하려면 격리된 Git worktree에서 실행하세요. --worktree 값은 파일시스템 경로가 아니라 GJC가 관리하는 sibling worktree의 branch-like 이름입니다.

gjc --tmux --worktree my-task-branch

이미 worktree 디렉터리를 직접 만들었다면 그 디렉터리로 들어가 실행합니다.

cd ../my-task-worktree && gjc --tmux

이미지 전달

시작 시에는 로컬 이미지 경로 앞에 @를 붙입니다.

gjc @screenshot.png "What should I change?"

TUI 안에서는 이미지를 시스템 클립보드에 복사한 뒤 Paste image from clipboard 키(Ctrl+V on Linux/macOS, Alt+V on Windows)를 쓰거나 #paste-image를 입력해 prompt action을 선택합니다. 클립보드를 쓸 수 없으면 @path/to/image.png 경로를 붙여넣거나 전달하세요.

프로바이더 인증

모델을 고르기 전에 적어도 하나의 프로바이더에 연결해야 합니다.

가장 간단한 방법은 API 키 환경 변수입니다. 쓰려는 프로바이더의 키를 export 하면 gjc가 자동으로 인식합니다.

전체 목록은 환경 변수를 참고하세요.

프리셋으로 커스텀 프로바이더를 등록할 수도 있습니다. 프리셋은 문서화된 환경 변수 이름을 참조하는 models.yml 항목만 작성하며, 비밀 값을 저장하지는 않습니다.

gjc setup provider --preset minimax
gjc setup provider --preset minimax-cn
gjc setup provider --preset glm

같은 프리셋을 TUI 안에서도 쓸 수 있습니다.

/provider add --preset glm
/provider add zai

OAuth 프로바이더는 환경 변수 대신 브라우저로 로그인합니다. Anthropic, OpenAI Code, Google(Gemini CLI / Antigravity), GitLab Duo에는 각각 내장된 브라우저 콜백 포트가 있습니다. 발급된 OAuth 자격 증명은 로컬 agent.db에 저장됩니다.

gjc가 프로바이더의 키를 해석할 때는 다음 순서를 따릅니다.

1. CLI --api-key
2. 저장된 API 키 (agent.db)
3. 저장된 OAuth 자격 증명 (agent.db)
4. 환경 변수
5. models.yml의 apiKey

그런 다음 TUI에서는 /model로, CLI에서는 --model / --models로 모델을 고릅니다. 자세한 내용은 모델과 자격 증명을 참고하세요.

고급: OAuth 리프레시 토큰을 노트북에서 공유 호스트로 옮기려면 모델과 자격 증명의 gjc auth-broker를 참고하세요.

research 모드 사용

직접 코드 변경보다 탐색 조사가 목적이면 rlm을 사용합니다.

gjc rlm

rlm은 영속 Python 커널과 제한된 python, read, web_search, search_tool_bm25, read-only bash, goal, complete_research 도구셋으로 노트북식 research/REPL 루프를 엽니다. 실행의 notebook.ipynb, report.md, metadata, agent-session 아티팩트는 .gjc/_session-<gjcSessionId>/rlm/<rlmSessionId>/ 아래에 기록됩니다.

루프 돌리기

Gajae-Code는 하나의 쓸모 있는 루프에 집중합니다.

deep-interview -> ralplan -> ultragoal
                         └─ 병렬 tmux 워커가 도움이 될 때만 team 실행

• deep-interview — 의도, 영향 범위, 비목표, 수용 기준을 명확히 합니다.
• ralplan — 변경 전에 계획을 세우고 비평합니다.
• ultragoal — 구현·수정·검증·증거 요약까지 작업을 끌고 갑니다.

병렬 tmux 워커가 도움이 될 때만 team을 더하세요. team은 tmux 세션 안($TMUX 설정)에서만 동작합니다. 먼저 셸에서 gjc CLI를 실행하세요(예: gjc --tmux).

구체적인 버그 수정 흐름은 이런 모습입니다.

/skill:deep-interview clarify the bug, affected behavior, non-goals, and acceptance checks
/skill:ralplan turn the clarified bug report into a reviewed fix plan
gjc ultragoal create-goals --brief-file <approved-plan>
# 병렬 작업일 때만 선택:
gjc team 2:executor "split implementation and verification for this bug fix"
gjc ultragoal complete-goals