Stream Deck Agent Cockpit

The point핵심

A physical control surface that never lies to you.

거짓말하지 않는 물리적 컨트롤 표면.

Most agent dashboards guess. They read a PID, watch a terminal title, scrape output, and render a confident “working…”. This one refuses to. A key shows a semantic state only when something reported it, and reverts to a coarse fact the moment that report expires.

대부분의 에이전트 대시보드는 추측합니다. PID를 읽고, 터미널 제목을 훔쳐보고, 출력을 긁어모아 자신 있게 “작업 중…”이라고 표시하죠. 이 콕핏은 그러지 않습니다. 키는 무언가가 실제로 보고했을 때만 의미론적 상태를 보여주고, 그 보고가 만료되는 즉시 검증된 개략 사실로 되돌아갑니다.

Predeclared operations only

사전 선언된 작업만 실행

A button press sends a named operation, never shell text. Commands are argv arrays run with shell=False. There is no raw-execution endpoint to abuse.

버튼을 누르면 셸 문자열이 아니라 이름이 정해진 작업이 전달됩니다. 명령은 argv 배열이며 shell=False로 실행됩니다. 악용할 수 있는 원시 실행 엔드포인트 자체가 없습니다.

Loopback and token-gated

루프백 바인딩 + 토큰 인증

The daemon binds to 127.0.0.1 and authenticates every request against a random token in a mode-0600 file. Nothing leaves the machine.

데몬은 127.0.0.1에만 바인딩하고, 모든 요청을 mode-0600 파일의 무작위 토큰으로 인증합니다. 어떤 것도 이 머신을 떠나지 않습니다.

State that expires

만료되는 상태

Every semantic report carries a TTL. When it lapses the key falls back to a probe result, so a dead agent can never leave a key stuck on “running”.

모든 의미론적 보고에는 TTL이 붙습니다. 만료되면 키는 프로브 결과로 되돌아가므로, 죽은 에이전트가 키를 “running”에 붙박아 두는 일이 없습니다.

Attach to sessions you already have open

이미 열어둔 세션 붙이기

A Claude Code hook binds live terminal sessions to predeclared slots, so tabs you opened yourself show up with real state. Tap a key to focus the pane. No terminal-title scraping.

Claude Code 훅이 실행 중인 터미널 세션을 미리 선언된 슬롯에 연결합니다. 직접 열어둔 탭도 실제 상태와 함께 나타나고, 키를 누르면 그 창이 앞으로 옵니다. 터미널 제목을 긁지 않습니다.

Logical bindings

논리적 바인딩

Controls bind to a stable controlId, never a row/column. Rearrange your deck in the Stream Deck app and the config stays valid.

컨트롤은 행/열 좌표가 아니라 안정적인 controlId에 묶입니다. Stream Deck 앱에서 배치를 바꿔도 설정은 그대로 유효합니다.

Guarded destructive gestures

보호되는 파괴적 제스처

Interrupt, kill, deploy, and merge require an explicit confirmation policy. A stray tap cannot stop a running agent.

중단, 종료, 배포, 머지에는 명시적인 확인 정책이 필요합니다. 실수로 한 번 누른 탭이 실행 중인 에이전트를 멈출 수 없습니다.

Nothing else touched

그 외에는 건드리지 않음

The skill owns its config, launchers, plugin UUID, and action instances. Stream Deck's internal profile database and third-party actions are never rewritten.

이 스킬은 자신의 설정, 런처, 플러그인 UUID, 액션 인스턴스만 소유합니다. Stream Deck 내부 프로필 데이터베이스와 서드파티 액션은 절대 다시 쓰지 않습니다.

How it works동작 방식

One local daemon is the entire policy boundary.

로컬 데몬 하나가 정책 경계의 전부입니다.

Stream Deck is the input device and the display. cockpitd decides what may run. Everything between them is a named operation over loopback.

Stream Deck은 입력 장치이자 디스플레이일 뿐이고, 무엇을 실행할지는 cockpitd가 결정합니다. 그 사이를 오가는 것은 루프백을 통한, 이름이 정해진 작업뿐입니다.

Stream Deck action or generated launcher Stream Deck 액션 또는 생성된 런처 tap · hold · dial탭 · 홀드 · 다이얼

HTTP on 127.0.0.1 + bearer token 127.0.0.1 HTTP + bearer 토큰

cockpitd loads config · authenticates · resolves controlId → operation 설정 로드 · 인증 · controlId → 작업 해석

predeclared argv, shell=False 사전 선언된 argv, shell=False

session / command adapter 세션 / 명령 어댑터 tmux, terminal, or your own adaptertmux, 터미널, 또는 직접 만든 어댑터

Claude Code Codex Pi JCode any CLI모든 CLI

Configure controls, not coordinates

좌표가 아니라 컨트롤을 설정합니다

// ~/.agent-cockpit/cockpit.json (version 3)// ~/.agent-cockpit/cockpit.json (버전 3)
"session.claude.main": {
  "label": "Claude",
  "adapter": { "type": "tmux", "target": "ac-claude-main" },
  "commands": {
    "launch":    { "argv": ["tmux","new-session","-d","-s","ac-claude-main","claude"] },
    "interrupt": { "argv": ["tmux","send-keys","-t","ac-claude-main","C-c"] }
  },
  "progress": { "source": "reporter", "staleAfterSeconds": 180 }
}

Report real state from a hook

훅에서 실제 상태를 보고합니다

# from an agent hook, CI step, or any script# 에이전트 훅, CI 스텝, 또는 아무 스크립트에서
python3 ~/.agent-cockpit/bin/cockpitctl.py \
  report session.claude.main running \
  --label "Running tests" --ttl 180

A percentage is accepted only when your workflow emits a real numerator and denominator — 27 of 40 tests, 8 of 10 files. It is never derived from elapsed time, token counts, or model prose.

백분율은 워크플로가 실제 분자와 분모를 내놓을 때만 허용됩니다 — 테스트 40개 중 27개, 파일 10개 중 8개처럼요. 경과 시간이나 토큰 수, 모델이 쓴 문장에서 유추하지 않습니다.

Two modes두 가지 모드

Start without compiling anything.

아무것도 컴파일하지 않고 시작하세요.

Launcher-only mode uses the built-in Stream Deck Open action against generated .command/.cmd files. Move to the native plugin only when you need a dynamic requirement that launchers genuinely cannot serve.

런처 전용 모드는 생성된 .command/.cmd 파일에 Stream Deck 내장 Open 액션을 연결합니다. 런처로는 정말 해결되지 않는 동적 요구가 생겼을 때만 네이티브 플러그인으로 넘어가세요.

Requirement요구 사항	Launcher-only런처 전용	Native plugin네이티브 플러그인
Tap launch / focus탭으로 실행 / 포커스	Yes	Yes
Static custom icon정적 커스텀 아이콘	Yes	Yes
Dynamic title / icon동적 제목 / 아이콘	No	Yes
Semantic state display의미론적 상태 표시	No	Yes
Long press길게 누르기	No	Yes
Dial rotate / press다이얼 회전 / 누름	No	Yes
Property Inspector	No	Yes
Custom plugin build required커스텀 플러그인 빌드 필요	No	Yes
MCP server requiredMCP 서버 필요	No	No

The repo ships a plugin template at templates/streamdeck-plugin/ — one generic action bound to a controlId — to adapt with the current official Stream Deck SDK. No prebuilt plugin binary is included.

저장소에는 templates/streamdeck-plugin/ 아래에 플러그인 템플릿이 들어 있습니다 — controlId에 묶이는 범용 액션 하나로, 현행 공식 Stream Deck SDK에 맞춰 적용하면 됩니다. 미리 빌드된 플러그인 바이너리는 포함되지 않습니다.

Evidence tiers근거 등급

What a key is allowed to claim.

키가 주장해도 되는 것.

Infrastructure presence and agent lifecycle are different facts, and the UI keeps them apart.

인프라의 존재 여부와 에이전트의 생애주기는 서로 다른 사실이며, UI는 둘을 섞지 않습니다.

Tier등급	Source출처	Allowed claims허용되는 주장
reported	Agent hook, RPC/event adapter, workflow callback, explicit reporter에이전트 훅, RPC/이벤트 어댑터, 워크플로 콜백, 명시적 리포터	Exact reported semantic state, plus explicit progress보고된 의미론적 상태 그대로, 그리고 명시적 진행률
coarse	tmux / process / probe exit codetmux / 프로세스 / 프로브 종료 코드	`present`, `offline`, `unavailable` only 만 가능
stale	Expired report plus a current probe만료된 보고 + 현재 프로브 결과	Coarse state, with the last report marked stale개략 상태, 마지막 보고는 만료로 표시
unknown	No valid report and no working probe유효한 보고도, 작동하는 프로브도 없음	Unknown / unavailable알 수 없음 / 사용 불가

Semantic states, only when reported

보고되었을 때만 쓰는 의미론적 상태

idle · running · needs_attention
blocked · succeeded · failed
Every report carries a timestamp, TTL, and source모든 보고에는 타임스탬프, TTL, 출처가 함께 담깁니다

Never inferred from

절대 유추하지 않는 근거

Process presence or a live PID프로세스 존재 여부나 살아 있는 PID
Elapsed time or a terminal title경과 시간이나 터미널 제목
Scraped terminal output or log-line counts긁어모은 터미널 출력이나 로그 줄 수
Token counts or model prose토큰 수나 모델이 쓴 문장

Install설치

Two steps: the skill, then the runtime.

두 단계: 스킬, 그다음 런타임.

The skill teaches your agent how to build and maintain the cockpit. The runtime is the daemon, CLI, and launcher generator that actually run on your machine.

스킬은 에이전트에게 콕핏을 만들고 유지하는 방법을 가르칩니다. 런타임은 실제로 머신에서 돌아가는 데몬, CLI, 런처 생성기입니다.

1 · Install the skill

1 · 스킬 설치

claude plugin marketplace add cskwork/streamdeck-agent-cockpit
claude plugin install streamdeck-agent-cockpit@streamdeck-agent-cockpit

Then type /streamdeck-agent-cockpit. Verify with claude plugin list.

그다음 /streamdeck-agent-cockpit을 입력하세요. claude plugin list로 확인합니다.

2 · Install the local runtime

2 · 로컬 런타임 설치

# inspect what is actually installed before assuming anything# 무엇이든 가정하기 전에 실제로 설치된 것을 확인
python3 scripts/probe_environment.py --json

# install ~/.agent-cockpit (config, daemon, CLI, launcher generator)# ~/.agent-cockpit 설치 (설정, 데몬, CLI, 런처 생성기)
python3 scripts/install_runtime.py

# start it, then check health# 실행한 뒤 상태 점검
python3 ~/.agent-cockpit/bin/cockpitd.py   --config ~/.agent-cockpit/cockpit.json
python3 ~/.agent-cockpit/bin/cockpitctl.py --config ~/.agent-cockpit/cockpit.json health

Requires Python 3.9+ and the Stream Deck application. tmux, a particular terminal, and the Stream Deck SDK are optional and only needed for the mode you choose. Full matrix in INSTALL.md.

Python 3.9+와 Stream Deck 애플리케이션이 필요합니다. tmux, 특정 터미널, Stream Deck SDK는 선택 사항이며 선택한 모드에서만 필요합니다. 전체 표는 INSTALL.md에 있습니다.

Verification검증

Checks that run, and checks only you can run.

자동으로 도는 검사, 그리고 당신만 할 수 있는 검사.

The repo separates what CI proves from what only a physical device can prove, and says so out loud rather than reporting a green tick for both.

이 저장소는 CI가 증명하는 것과 실제 장치에서만 증명할 수 있는 것을 구분하고, 둘 다에 초록 체크를 찍는 대신 그 차이를 분명히 밝힙니다.

Automated

자동화된 검사

python3 -m compileall -q bin scripts tests
python3 -m unittest discover -s tests -v
python3 scripts/validate_cockpit.py assets/cockpit.example.json
python3 scripts/smoke_test.py

On-device, by you

실제 장치에서, 직접

Tap focuses an existing session; tap launches a missing one, then focuses it탭이 기존 세션에 포커스하고, 없는 세션은 실행한 뒤 포커스하는지
Hold does not fire on a normal tap평범한 탭에서 홀드가 발동하지 않는지
Interrupt reaches only the intended session인터럽트가 의도한 세션에만 전달되는지
Daemon-down and invalid-control states are visible on the key데몬 다운·잘못된 컨트롤 상태가 키에 보이는지
Restarting Stream Deck, the daemon, and the terminal corrupts nothingStream Deck·데몬·터미널을 재시작해도 설정이 깨지지 않는지
Uninstalling leaves unrelated profiles intact제거해도 관련 없는 프로필이 그대로 남는지

Deliberate limitations의도적인 한계

What this does not do.

이것이 하지 않는 일.

No live state in launcher-only mode

런처 전용 모드에는 실시간 상태가 없습니다

Launchers cannot display state, distinguish a hold, or read a dial. That is the price of needing no compiled plugin.

런처는 상태를 표시하거나, 홀드를 구분하거나, 다이얼을 읽을 수 없습니다. 플러그인을 컴파일하지 않아도 되는 대가입니다.

No prebuilt plugin binary

미리 빌드된 플러그인 바이너리 없음

The plugin template must be adapted and built with the current official Stream Deck SDK on your machine.

플러그인 템플릿은 현행 공식 Stream Deck SDK로 직접 적용하고 빌드해야 합니다.

No arbitrary profile editing

임의의 프로필 편집 없음

The official plugin boundary offers no safe generic API for rewriting profiles or driving unrelated third-party actions. Multi Actions are the documented path.

공식 플러그인 경계는 프로필을 다시 쓰거나 관련 없는 서드파티 액션을 조작할 안전한 범용 API를 제공하지 않습니다. 문서화된 방법은 Multi Action입니다.

Focus is terminal-specific

포커스 동작은 터미널마다 다릅니다

Whether a window truly comes forward depends on your terminal and OS, and must be verified on the actual device.

창이 실제로 앞으로 나오는지는 사용하는 터미널과 OS에 달려 있으며, 실제 장치에서 확인해야 합니다.