AI가 작성한 설계 문서를 에이전트 옆에서 읽기 위해 터미널을 직접 제작했습니다

최근 AI 에이전트에게 설계 문서를 작성하게 하는 경우가 늘었습니다. 단순히 작성만 시키고 끝내는 것이 아니라, 그것을 읽고, 수정하게 하고, 다시 읽는 과정을 반복합니다.

그 과정마다 에디터의 미리보기로 전환했다가, 다 읽으면 터미널로 돌아오는 것을 반복했습니다.

이러한 왕복(往復) 과정을 없애기 위해, 설계 문서를 에이전트 옆 패인에서 볼 수 있는 터미널을 만들었습니다.

orzma는 터미널 안에 웹페이지를 그릴 수 있는 터미널 에뮬레이터입니다. 함께 제공되는 Markdown 뷰어 orzmd를 옆 패인에 열면, AI가 설계 문서를 수정할 때마다 표시가 바뀝니다.

macOS에서는 Homebrew로 설치할 수 있습니다.

brew install --cask not-elm/orzma/orzma

orzma를 실행하고 그 패인 안에서 설계 문서를 엽니다.

orzmd design.md

앞부분은 사용법이고, 뒷부분은 orzmd를 지탱하는 Webview 프로토콜에 대한 내용입니다.

이전에는 에디터의 미리보기와 왔다 갔다 했습니다

번거로웠던 점은 터미널에서 눈을 떼고 있는 순간이었습니다. 미리보기를 읽고 있으면, 에이전트의 출력이 보이지 않게 됩니다. 돌아왔을 때는 질문이 위로 흘러가 있어서, 출력 내용을 거슬러 올라가서 무엇을 물었는지 찾아야 했습니다.

에디터의 미리보기만으로 충분한 상황도 많습니다. 터미널 옆에 Markdown을 표시할 수 있는 도구도 이미 몇 가지 있으며, 에이전트 옆에서 설계 문서를 읽는 것만으로는 그것들로도 가능합니다.

orzma가 다른 점은 한 가지입니다. 설계 문서를 표시하는 orzmd는 터미널에 내장된 기능이 아니라, 공개된 프로토콜을 사용하는 일반적인 프로그램이라는 것입니다. 따라서 같은 메커니즘을 자신의 TUI(Text User Interface)에서도 사용할 수 있습니다.

orzmd로 설계 문서를 읽기

저장하면 표시가 업데이트됩니다

orzmd design.md

이라고 입력하면, 그 패인에 설계 문서가 그려집니다. 파일이 저장될 때마다 다시 그려지며, 스크롤 위치는 그대로 유지됩니다. AI가 긴 설계 문서의 중간 부분을 수정해도, 읽던 곳을 놓치지 않습니다.

옆 패인에서 AI에게

import json, os, socket
html = ("<meta charset=utf-8><style>body{margin:0;height:100vh;"
"display:flex;background:linear-gradient(120deg,#73e,#e49,#f90)}"
...

Python 17행으로, 출력 중간에 Web 페이지가 나옴

hello로 자신을 소개하고, register로 페이지를 등록합니다. 반환된 instance를 mount에 전달하면, 커서 위치에 10줄 60자짜리 페이지가 배치됩니다.

등록과 배치를 경로를 나눈 이유는 다음과 같습니다.

• 놓는 장소는 커서 위치로 결정됩니다. 따라서 배치만은 문자와 같은 출력 흐름을 타는 이스케이프 시퀀스로 했습니다.
• 페이지 내용은 양이 많고, 주고받음은 양방향입니다. 여기는 소켓(socket) 경유로 했습니다.
• Windows에서는 ConPTY가 이 이스케이프 시퀀스를 파기하므로, 배치도 소켓으로 보내고 있습니다.

페이지 쪽에는 window.orzma가 준비됩니다. 다음 코드는 사용 예시입니다. 위의 Python 예제는 응답을 하지 않으므로, 그대로 조합하면 call이 끝나지 않습니다.

// 프로그램을 호출하고 응답을 기다림
const res = await window.orzma.call("save", { text: "hi" });
// 프로그램으로부터 이벤트를 받음
...

await는 module 스크립트나 async 함수 안에서 사용합니다.

op 목록, 에러 코드, 보안 모델은 리퍼런스에 있습니다.

자신의 TUI에 Webview를 배치하기

같은 메커니즘을 자신의 TUI(Terminal User Interface)에서도 사용할 수 있습니다. Rust의 ratatui용으로 SDK ratatui_orzma를 준비했습니다.

cargo add ratatui_orzma [email protected]

연결하고, 페이지를 등록하고, 백엔드를 감싸고(wrap), 위젯을 그립니다. 이 4가지 절차로 표시할 수 있습니다.

let orzma = Orzma::connect()?;
let view = orzma.register(Webview::inline(HTML))?;
// crossterm의 백엔드를 OrzmaBackend로 감쌈
...

위젯은 놓는 장소만 기록하면, OrzmaBackend가 그릴 때마다 그 장소를 orzma에게 전달합니다.

orzmd와 orzbrowser도 이 SDK로 만들고 있습니다. 페이지 쪽에는 window.orzma의 타입 지정 클라이언트 @orzma/web이 있습니다.

절차는 튜토리얼에 있습니다.

마치며

설계서를 읽기 위해 창을 전환할 필요가 없어졌습니다. 에이전트에게 지시를 내리는 페인(pane) 옆에서, 수정되어 가는 설계서를 읽고 있습니다.

orzma 자체의 설계서도 같은 방식으로 읽고 있습니다.

터미널에 Web 페이지를 배치할 수 있게 되면서, 설계서 외에도 그림이나 그래프, 개발 중인 화면을 에이전트 옆에 나란히 놓을 수 있게 되었습니다. 미흡한 점은 아직 많지만, 저는 매일 이것으로 작업하고 있습니다.

사용해 보고 싶거나 이 메커니즘이 흥미하다고 생각하시면, GitHub에서 스타를 달아주시면 큰 힘이 됩니다.

오류나 "이것 없이는 쓸 수 없다"는 요청사항이 있다면, Issue로 알려주세요.

Discussion