AI 에이전트와 작업

Zshell 자동화는 주로 AI 코딩 에이전트를 위한 기능입니다. 에이전트가 Zshell 분할 창을 다루고 다른 에이전트와 협업할 수 있는 안전한 인터페이스를 제공하며, 사용자가 별도의 명령 언어를 배울 필요는 없습니다.

AI 통합은 기본적으로 켜져 있습니다. 평소처럼 코딩 에이전트에게 요청하세요. 에이전트는 사용 중인 분할 창의 포커스를 빼앗지 않고 백그라운드 창 생성, 작업 에이전트 실행, 명령 실행, 결과 대기와 응답 전달을 수행할 수 있습니다.

명령 결과 기다리기링크 복사

테스트나 빌드처럼 종료되는 명령은 에이전트가 명령 자체의 종료 코드와 실행 시간을 기다린 뒤 저장된 최근 터미널 출력을 읽을 수 있습니다. 대기 시간이 초과되어도 명령은 계속 실행되며 같은 작업을 다시 기다릴 수 있습니다. 기다리는 동안 포커스를 가져가지 않습니다. Zshell이 시작한 원래 로컬 zsh의 빈 프롬프트가 필요하며 중첩 셸, SSH, 사용자 지정 시작 프로그램은 지원하지 않습니다. 최근 출력에는 이전 명령이나 프롬프트가 포함될 수 있고 길이가 제한됩니다. 전체 기록이 필요하면 에이전트에게 출력을 파일에 저장하도록 요청하세요.

원래 셸을 종료하거나 바꾸는 exit, logout, exec의 직접 실행은 거부됩니다. 이러한 명령은 /bin/sh -c로 하위 프로세스에서 실행하세요.

설정링크 복사

설정 → 자동화 → AI를 확인하세요. 기본적으로 켜져 있지만 전에 껐다면 다시 켠 다음 새 터미널을 열거나 이미 실행 중이던 에이전트를 재시작하세요.

Zshell은 Codex, Claude Code, Gemini CLI, Grok Build, OpenCode, Cursor Agent, Aider, Amp 및 Pi를 지원합니다. 이 기능과 충돌하는 기존 에이전트 설정을 발견하면 해당 설정을 건드리지 않고 스위치를 이전 상태로 되돌린 뒤 설정 화면에 오류를 표시합니다.

평소 말하듯 요청하기링크 복사

원하는 결과를 에이전트에게 말하세요. 예를 들면 다음과 같습니다.

관련 테스트를 백그라운드 분할 창에서 실행하고 실패한 항목을 알려 줘.

이 버그를 다른 Codex 에이전트에게 맡긴 다음 결과를 검토해 줘.

API 작업 중인 에이전트에게 스키마가 준비됐는지 물어보고, 답을 테스트 중인 에이전트에게 전달해 줘.

옆에서 개발 서버를 시작하고 준비될 때까지 기다린 다음 URL을 알려 줘.

백그라운드 에이전트가 작업을 마쳤는지 확인해 줘. 막혀 있다면 무엇이 필요한지 알려 줘.

에이전트가 Zshell 자동화 인터페이스를 대신 다룹니다. 사용자가 Zshell 자동화 명령을 입력하거나 외울 필요가 없습니다.

분할 창 간 에이전트 협업링크 복사

관련 작업을 여러 Zshell 분할 창에 나누고 주 에이전트에게 조율을 맡길 수 있습니다. 예를 들어 한 에이전트는 API를 만들고 다른 에이전트는 테스트를 갱신합니다. 조율 에이전트는 특정 작업자에게 조사 결과를 요청하고, 후속 요청을 보내며, 유용한 결과를 다른 작업자에게 전달한 다음 종합한 답을 사용자에게 돌려줍니다. 작업자들은 서로 다른 지원 코딩 도구를 사용할 수도 있습니다.

병렬 작업에서 맥락을 복사해 붙여넣는 단계를 줄일 수 있습니다. 각 에이전트는 자기 분할 창에서 대화를 유지하고, 조율 에이전트는 다른 작업자에게 필요한 질문, 갱신 내용이나 결과만 전달합니다.

후속 요청을 보냈다고 작업이 끝난 것은 아닙니다. 조율 에이전트는 작업자를 기다리고 결과를 읽은 뒤 성과를 확인합니다. 다른 에이전트의 메시지도 사용자의 승인으로 취급하지 않습니다. 권한, 자격 증명, 신뢰 여부와 파괴적인 작업의 결정권은 여전히 사용자에게 있습니다.

실행 중에도 계속 작업하기링크 복사

위임된 분할 창은 표시해 달라고 요청하지 않는 한 백그라운드에 머뭅니다. 제공자의 기본 수명 주기 통합이 상태를 보고하면 Zshell은 에이전트의 창과 탭에 표시합니다.

Zshell은 Codex, Claude Code, Pi, OpenCode, Grok의 기본 수명 주기 이벤트를 우선하고, 그다음 프로그램의 명시적 보고를 사용합니다. 상태 배지에 마우스를 올리거나 Agents를 열면 출처, 대기 이유, 진행률, 하위 작업을 볼 수 있습니다. Codex 후크는 먼저 /hooks에서 검토하고 신뢰해야 하며 Zshell은 이를 우회하지 않습니다.

기본 보고가 없으면 인식된 에이전트의 현재 화면 하단만 제한된 범위로 검사합니다. 화면 추론은 출처가 표시되며 완료 보고, 알림, zshell +agent wait의 완료 조건에 사용되지 않고 프롬프트를 승인하지도 않습니다. 분할 창과 실제 결과를 확인하세요.

프로그램은 zshell +agent report로 진행률을 보고하고 zshell +agent clear로 자신의 보고를 지울 수 있습니다. 120초 동안 업데이트가 없거나 소유 프로세스가 종료되면 보고가 만료됩니다.

통합 기능이 에이전트의 완료나 입력 필요 상태를 보고하면 Zshell이 알림도 보낼 수 있습니다. Cmd+Shift+A로 보고된 에이전트 중 확인이 필요한 다음 항목으로 이동하세요.

계정 사용량과 한도링크 복사

설정 → 자동화 → 계정 사용량은 Claude Code와 Codex에서 제공하는 계정 한도를 보여 줍니다. 사용 비율, 보고된 경우 초기화 시각, 마지막 갱신 시각을 포함합니다. 사용량 새로 고침으로 최신 데이터를 다시 불러오세요.

Codex는 계정 한도를 보고할 수 있는 CLI가 설치되어 있고 로그인되어 있어야 합니다. Claude Code 사용량은 Zshell이 제공자의 상태 표시줄 사용량 보고를 받았을 때 표시됩니다. 데이터가 있을 때만 이 구역이 나타나며 지원하는 시간 구간은 제공자와 계정에 따라 달라집니다. 표시되는 값은 계정 한도이며 포커스된 세션의 토큰 총량이 아닙니다.

일반적인 작업 순서링크 복사

1. Zshell 터미널에서 평소 사용하는 코딩 에이전트를 시작합니다.
2. 범위가 정해진 작업을 위임하거나 백그라운드에서 실행하거나 다른 에이전트와 조율해 달라고 요청합니다.
3. Zshell이 프로젝트 배치에 위임된 작업을 표시하는 동안 현재 분할 창에서 작업을 계속합니다.
4. 제공자가 보고하는 작업 중, 차단됨 또는 완료 배지가 있다면 확인합니다. 도구가 수명 주기를 보고하지 않으면 창을 열어 대화나 터미널 출력을 직접 확인합니다.
5. 결과 파일을 Git 패널에서 검토하고 차이를 확인한 뒤 남길 내용을 결정합니다.

결정권은 사용자에게링크 복사

• 에이전트 자동화는 현재 Zshell 프로젝트 안에 한정되며 다른 프로젝트나 창의 분할 창에 접근할 수 없습니다.
• 명시적으로 요청하지 않는 한 백그라운드 작업이 포커스를 가져가지 않습니다.
• Zshell은 권한, 자격 증명, 신뢰 여부나 파괴적인 작업 확인에 대신 응답하지 않습니다. 제공자가 차단 상태를 보고하면 결정을 사용자에게 돌려줍니다.
• 완료 보고는 결과를 검토하라는 신호이며, 에이전트의 변경을 자동 승인한다는 뜻이 아닙니다.

에이전트가 Zshell을 사용하지 않는 경우링크 복사

• 설정 → 자동화 → AI가 켜져 있는지 확인하세요.
• 현재 터미널이 설정을 켜기 전부터 열려 있었다면 새 Zshell 터미널을 여세요.
• 설정을 켤 때 이미 실행 중이던 에이전트를 재시작하세요.
• 설정 화면에 인라인 설정 오류가 있는지 확인하세요.
• 이 작업 방식을 사용하게 하려면 명확히 “백그라운드 Zshell 분할 창”이나 “위임된 Zshell 에이전트”를 요청하세요.

원래 대화 재개링크 복사

에이전트 대화 재개를 켜면 원래 PTY를 사용할 수 없는 터미널 창을 복원할 때 해당 창에 기록된 Claude Code, Codex, Pi 또는 OpenCode 대화를 재개합니다. 같은 디렉터리를 쓰는 여러 창도 각자의 대화에 연결됩니다.

기존 제공업체 설정에 Claude Code와 Codex의 SessionStart 훅, Pi 확장, OpenCode TUI 플러그인을 설치합니다. 다른 훅, 플러그인, 설정 및 JSONC 주석을 보존합니다. 제공업체가 요청하면 Claude Code 신뢰 확인에서 훅을 활성화하고 Codex의 /hooks에서 새 훅을 승인하세요. 설치 전부터 실행 중이던 에이전트는 다시 시작해야 합니다.

통합에서 보고한 검증된 루트 대화만 복원합니다. 검증된 대화 ID가 창과 일치하면 공유 Codex app-server 세션을 지원하며, 모호한 경우 연결하지 않습니다. 원격 호스트의 대화는 원격 세션 공유를 참고하세요. OpenCode는 TUI 플러그인 API가 필요하며 이전 버전, 헤드리스 서버 및 opencode attach는 지원하지 않습니다. 하위 에이전트는 부모 창의 대화를 바꿀 수 없습니다. Pi는 저장된 세션 파일이 필요합니다.

확인된 ID, 원래 작업 디렉터리 또는 Pi 파일이 없으면 새 셸을 엽니다. CLI를 찾을 수 없어도 셸로 돌아갑니다. 임의의 시작 명령을 재실행하거나 최근 대화를 선택하지 않습니다. 삭제된 대화 같은 제공업체 오류는 CLI가 표시합니다.

저장된 대화 검색 및 재개링크 복사

에이전트 → 에이전트 대화 기록, 프로젝트 사이드바 위쪽의 시계 버튼을 여세요. 제목, 제공업체, 프로젝트, 대화 ID, 작업 디렉터리나 설정 디렉터리로 프로젝트 전체를 검색할 수 있습니다. Zshell은 최근 200개의 검증된 로컬 대화를 저장하며, 에이전트와 분할 창 종료 및 앱 재시작 후에도 기록을 유지합니다. 최근은 보관되지 않은 검색 결과 20개, 전체는 보관된 기록까지, 보관됨은 보관된 기록만 표시합니다.

열린 대화는 대화 표시, 저장된 대화는 대화 재개를 선택하세요. Zshell은 열린 분할 창을 재사용하고, 살아 있는 PTY에 다시 연결하거나 원래 디렉터리와 설정으로 제공업체의 정확한 대화를 재개합니다. 수동 재개에는 AI 통합이 필요하지만 자동 대화 복원 설정은 꺼져 있어도 됩니다. 작업 또는 설정 디렉터리가 없거나 Pi 파일이 없거나 ID가 일치하지 않으면 새 분할 창을 만들기 전에 오류를 표시합니다.

보관은 최근 목록에서 기록을 숨기고 보관 해제는 되돌립니다. **삭제…**는 Zshell 기록만 삭제하며 제공업체의 대화 파일은 유지합니다.

Zshell 분할 창 안에서는 zshell +agent history --all과 zshell +agent resume --id HISTORY_UUID가 해당 창의 프로젝트에 적용됩니다. 일반 외부 터미널에서는 Zshell을 실행한 상태로 프로젝트 UUID를 확인한 뒤 명시적으로 선택하세요:

zshell +agent history projects
zshell +agent history --project PROJECT_UUID --all
zshell +agent resume --project PROJECT_UUID --id HISTORY_UUID --focus

CLI 재개는 기본적으로 백그라운드에서 진행되며 --focus를 추가해야 포커스가 바뀝니다. 프로젝트가 여러 창에 열려 있으면 history projects의 --window WINDOW_UUID로 선택하세요. 앱 인스턴스가 여러 개라면 CLI가 안내하는 비공개 연결 파일의 절대 경로를 --connection PATH로 지정하세요. 이 대상 옵션은 외부 터미널용이며 분할 창 프로세스는 원래 프로젝트 범위를 유지합니다.

프로젝트 실시간 이벤트 구독링크 복사

Zshell 터미널에서 zshell +events를 실행하면 해당 프로젝트와 창의 이후 변경을 NDJSON으로 받습니다. --pane UUID, 반복 가능한 --event NAME, --once, --timeout MS(0은 무제한)를 지원하며 폴링하지 않습니다.

세션과 창의 생성·종료, 포커스, Agent 진행률·주의·완료 및 명령 완료를 알립니다. 첫 stream.ready는 sequence 0이며 일치하는 이벤트마다 증가합니다. 각 줄에는 version, event, stream_id, sequence, Unix 밀리초 time, project_id, data가 있습니다. 과거 이벤트를 재생하지 않습니다. 작업 결과는 +pane wait --task UUID로 읽습니다.

최대 32개 구독, 큐당 256프레임·1 MiB, 프레임당 64 KiB입니다. 지연되면 가능할 경우 stream.lagged를 보낸 후 연결을 끊고, 2초 동안 쓰지 못해도 닫습니다. 지연·예기치 않은 연결 종료·순서 오류는 0이 아닌 코드로 종료합니다. 다시 구독하고 현재 상태를 읽으세요. 소유 터미널 종료, 토큰 교체, 다른 프로젝트나 창으로 이동 시 구독이 끝납니다. 외부 제어와 --project는 지원하지 않으며 환경 변수를 지워도 권한이 커지지 않습니다. --once의 불일치 시간 초과는 124, 일반 시간 초과는 0입니다.

zshell +events --event command.task.finished --once --timeout 30000

pane.updated: data.from → data (tab_id, pane_id, terminal_id, content).