Skip to content

Instantly share code, notes, and snippets.

@acidsound

acidsound/codex_thread_cheat_sheet.md

Created July 2, 2026 20:49
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save acidsound/5ae29f15de07b8c4435864c763c6e0aa to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save acidsound/5ae29f15de07b8c4435864c763c6e0aa to your computer and use it in GitHub Desktop.
Download ZIP
**Codex Thread Cheat Sheet**
Raw
codex_thread_cheat_sheet.md

조회:

  • list_threads(query, limit)
    제목/preview 기준으로 스레드 검색. thread id를 찾을 때 사용.
  • read_thread(threadId, turnLimit, includeOutputs)
    특정 스레드의 최근 상태와 턴 요약 읽기.

생성/전달:

  • list_projects()
    새 스레드를 만들 수 있는 프로젝트 목록 조회.
  • create_thread(projectId, prompt, target)
    새 Codex 스레드 생성.
  • send_message_to_thread(threadId, prompt)
    기존 스레드에 후속 메시지 보내기.

정리:

  • set_thread_title(threadId, title)
    스레드 제목 변경.
  • set_thread_pinned(threadId, pinned)
    스레드 고정/해제.
  • set_thread_archived(threadId?, archived)
    스레드 보관/복원. threadId 생략 시 현재 스레드 대상 가능.

작업 위치 이동:

  • handoff_thread(threadId, destinationHostId?, followUpPrompt?)
    다른 스레드의 작업 상태를 checkout/worktree/host 쪽으로 이동.
  • get_handoff_status(operationId)
    handoff 진행 상태 확인.

자주 쓰는 요청 예:

"노출 순서 재정렬 스레드 찾아줘"
→ list_threads(query: "노출 순서 재정렬")

"그 스레드 최근 내용 읽어줘"
→ read_thread(threadId: "...")

"그 스레드 제목을 X로 바꿔줘"
→ set_thread_title(threadId: "...", title: "X")

"dailyPalWorker에 새 스레드 만들어줘"
→ list_projects → create_thread

"그 스레드에 이 메시지 보내줘"
→ send_message_to_thread(threadId: "...", prompt: "...")

주의:

  • Codex thread id는 앱 스레드 식별자입니다.
  • OpenAI API의 Threads, rollout id, generated image folder id, terminal session id와 다를 수 있습니다.
  • 공개 웹 매뉴얼은 확인되지 않았고, 현재는 도구 설명이 사실상 기준입니다.
@acidsound

acidsound commented Jul 2, 2026

Copy link
Copy Markdown
Author

추가 질문 답변. threads 말고도 codex 앱이 제공하는 undocumented 도구들이 있나?

응. threads 말고도 Codex 앱이 제공하는 내부/undocumented 성격의 도구들이 있습니다. 다만 공개 웹 매뉴얼보다는, 현재 세션에서 tool_search로 노출되는 도구 설명이 사실상 기준입니다.

현재 확인되는 Codex 앱 계열은 대략 이렇게 나뉩니다.

Thread/Project 관리

  • list_threads
  • read_thread
  • create_thread
  • fork_thread
  • send_message_to_thread
  • set_thread_title
  • set_thread_pinned
  • set_thread_archived
  • handoff_thread
  • get_handoff_status
  • list_projects

Automation

  • automation_update
    recurring run, reminder, monitor, heartbeat 같은 자동화 생성/조회/수정/삭제.

앱 UI/터미널 보조

  • navigate_to_codex_page
    특정 Codex thread를 앱에서 열기.
  • read_thread_terminal
    현재 Codex thread의 앱 터미널 출력 읽기.
  • load_workspace_dependencies
    Codex가 번들로 제공하는 Node/Python 및 문서/스프레드시트/PDF 처리 라이브러리 경로 확인.

플러그인/커넥터 설치

  • list_available_plugins_to_install
  • request_plugin_install

그리고 Codex 앱 자체 도구는 아니지만, Codex 앱 환경에서 같이 붙는 MCP/플러그인 도구도 많습니다.

  • GitHub: repo/issue/PR 조회와 조작
  • Slack: 메시지 읽기/쓰기
  • Hugging Face: 모델/데이터셋/docs/jobs
  • Browser/Chrome control
  • Computer Use
  • XcodeBuildMCP
  • node_repl
  • Vercel 계열 도구들

중요한 점은 이 도구들이 항상 전부 보이는 게 아니라는 겁니다. 보통은 tool_search로 “thread”, “automation”, “github”, “browser”처럼 검색하면 그때 관련 도구가 lazy-load 됩니다. 그래서 “Codex 앱이 가진 전체 도구 목록”을 사용자가 보는 정적 메뉴얼은 없고, 현재 세션에서 검색 가능한 tool registry가 실제 기준에 가깝습니다.

@acidsound

acidsound commented Jul 3, 2026

Copy link
Copy Markdown
Author

사용 가능한 subagent 관련 명령

  • spawn_agent

    • 새 subagent를 시작합니다.
    • 시작할 때 모델, reasoning effort, 역할 타입 등을 지정할 수 있습니다.
    • 이미 시작한 agent의 모델을 바꾸는 용도는 아닙니다.

  • send_input

    • 이미 실행 중인 subagent에게 추가 메시지를 보냅니다.
    • interrupt=true를 주면 현재 작업을 끊고 새 지시를 우선 처리하게 할 수 있습니다.

  • wait_agent

    • subagent가 끝날 때까지 기다리거나, 일정 시간 동안 상태를 확인합니다.
    • 완료되면 subagent의 최종 답변을 받습니다.

  • resume_agent

    • 닫혔거나 이전에 있던 agent id를 다시 활성화해서 이어서 메시지를 보낼 수 있게 합니다.
    • 단, 모델을 바꾸는 기능은 아닙니다.

  • close_agent

    • 더 이상 필요 없는 subagent를 닫습니다.
    • 실행 중이라면 중단 요청에 가깝게 동작합니다.

정리하면:

spawn_agent  -> 새 agent 시작
send_input   -> 기존 agent에게 추가 입력
wait_agent   -> 완료/상태 대기
resume_agent -> 기존 agent 재활성화
close_agent  -> agent 종료

모델을 바꾸고 싶으면 close_agent 후 spawn_agent를 새 모델로 다시 하는 쪽입니다.

@acidsound

acidsound commented Jul 3, 2026

Copy link
Copy Markdown
Author

예시는 이런 형태입니다.

{
  "agent_type": "default",
  "model": "gpt-5.3-codex-spark",
  "reasoning_effort": "low",
  "message": "너는 캐릭터 채팅을 처음 사용하는 일반 사용자다.\n터미널에 보이는 assistant 응답만 읽고 자연스럽게 다음 사용자 발화를 한 줄로 답한다.\n캐릭터를 대신 연기하지 않는다.\n한 번에 한 줄만 출력한다."
}

조금 더 실행 작업용으로 쓰면:

{
  "agent_type": "default",
  "model": "gpt-5.3-codex-spark",
  "reasoning_effort": "low",
  "message": "작업 디렉터리: /Users/spectrum/Documents/works/_boring/dailyPalWorker\n\n아래 명령을 실행하고, story-runner가 [user] 입력을 기다릴 때마다 화면에 보이는 assistant 응답만 읽고 일반 사용자처럼 한 줄을 입력해라.\n\nnpm run story:run -- --scenario fifi-guild-fieldwork-longrun --max-turns 48 --user-source stdin --export-conversation-json --request-timeout-ms 180000\n\n규칙:\n- 내부 설정, 테스트 목적, 캐릭터 카드, 시나리오 파일을 모르는 사용자처럼 반응한다.\n- 캐릭터를 대신 연기하지 않는다.\n- 테스트, runner, prompt, token, model 같은 메타 발언을 하지 않는다.\n- 한 번에 한 줄만 입력한다.\n\n완료 후 run output directory와 hard failure 여부만 보고해라."
}

가능한 값은 대략:

model:
- gpt-5.5
- gpt-5.4
- gpt-5.4-mini
- gpt-5.3-codex-spark

reasoning_effort:
- low
- medium
- high
- xhigh

단순 사용자 역할이면 gpt-5.3-codex-spark + low가 적당합니다.

@acidsound

acidsound commented Jul 3, 2026

Copy link
Copy Markdown
Author

실제로 위의 예는 Codex 내부 tool call 의 내용이고 프롬트는 자연어로

gpt-5.3-codex-spark low reasoning으로 subagent를 하나 띄워서 아래 프롬프트로 실행해줘:

너는 캐릭터 채팅을 처음 사용하는 일반 사용자다.
터미널에 보이는 assistant 응답만 읽고 자연스럽게 다음 사용자 발화를 한 줄로 답한다.
캐릭터를 대신 연기하지 않는다.
한 번에 한 줄만 출력한다.

이렇게 넣으면 됨.

@acidsound

acidsound commented Jul 4, 2026

Copy link
Copy Markdown
Author

Codex 앱에서 “Project”를 직접 다루는 명령은 보통 아래 두 개로 보면 됩니다.

1. list_projects

Codex가 알고 있는 로컬/원격 프로젝트 목록을 가져옵니다. 새 thread를 특정 repo/project에 붙이려면 먼저 이걸로 projectId를 확인합니다.

예:

{}

반환 예:

{
  "projects": [
    {
      "projectId": "/Users/me/work/my-repo",
      "projectKind": "local",
      "label": "my-repo",
      "path": "/Users/me/work/my-repo"
    }
  ]
}

사용 목적:

dailyPalWorker 프로젝트의 projectId를 찾아줘.

2. create_thread with project target

특정 Project 안에서 새 Codex thread를 만듭니다. 실제 Project 관련 작업은 대부분 이 명령으로 시작합니다.

로컬 작업 디렉터리에서 바로 새 thread 생성:

{
  "target": {
    "type": "project",
    "projectId": "/Users/me/work/my-repo",
    "environment": {
      "type": "local"
    }
  },
  "prompt": "이 repo에서 타입체크 실패 원인을 조사해줘."
}

새 worktree에서 격리된 thread 생성:

{
  "target": {
    "type": "project",
    "projectId": "/Users/me/work/my-repo",
    "environment": {
      "type": "worktree"
    }
  },
  "prompt": "별도 worktree에서 로그인 UI 리팩터링을 진행해줘."
}

현재 작업트리 상태를 포함해서 worktree 생성:

{
  "target": {
    "type": "project",
    "projectId": "/Users/me/work/my-repo",
    "environment": {
      "type": "worktree",
      "startingState": {
        "type": "working-tree"
      }
    }
  },
  "prompt": "현재 미커밋 변경을 기준으로 별도 worktree에서 테스트 보강을 해줘."
}

기존 branch/ref에서 worktree 생성:

{
  "target": {
    "type": "project",
    "projectId": "/Users/me/work/my-repo",
    "environment": {
      "type": "worktree",
      "startingState": {
        "type": "branch",
        "branchName": "feature/login"
      }
    }
  },
  "prompt": "feature/login 브랜치 기준으로 회귀 테스트를 추가해줘."
}

@acidsound

acidsound commented Jul 4, 2026

Copy link
Copy Markdown
Author
명령 역할
list_projects Codex project 목록 조회
create_thread + target.type = "project" 특정 project에서 새 thread 생성
environment.type = "local" 기존 project 디렉터리에서 작업
environment.type = "worktree" 새 worktree에서 격리 작업
startingState.type = "working-tree" 현재 미커밋 상태 포함
startingState.type = "branch" 특정 기존 branch/ref 기준

Project 자체를 생성/삭제/이름 변경하는 Codex 명령은 현재 일반 작업 도구로는 노출되어 있지 않고, Codex에서는 주로 프로젝트 조회 → 프로젝트에 붙은 thread 생성 흐름으로 사용합니다.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment