Agent-first persistence
에이전트 작업이 끊기지 않습니다
Named PTY sessions keep running after clients detach, so long agent tasks survive terminal churn.
이름을 붙인 PTY 세션은 클라이언트가 접속을 끊어도 계속 실행됩니다. 오래 걸리는 에이전트 작업은 터미널을 닫았다 다시 열어도 중단되지 않습니다.
Persistent terminals for AI agents · v1.0.32 current
AI 에이전트 작업을 오래 유지하는 터미널 · v1.0.32 current
lterm keeps agents running.
lterm은 에이전트 작업을 끊기지 않게 유지합니다.
A lightweight tmux-compatible session daemon for Claude Code, Codex CLI, Gemini CLI, OpenCode, Grok Build CLI through custom profiles, and other terminal-first agent workflows — including mobile SSH reconnects and cmux panes, now current in 1.0.32 with authoritative exit evidence, bounded recovery, and race-safe session identity finalization.
Claude Code, Codex CLI, Gemini CLI, OpenCode, custom profile로 실행하는 Grok Build CLI 같은 터미널 기반 AI 에이전트 워크플로를 위해 만든 가벼운 tmux 호환 세션 데몬입니다. 모바일 SSH 재접속과 cmux pane도 함께 고려했고, 1.0.32 현재 릴리스는 권위 있는 exit evidence, 상한이 있는 recovery, 경쟁에 안전한 session identity finalization을 포함합니다.
Now live: v1.0.32. Authoritative exit triggers, crash-recoverable lifecycle journals, non-blocking cleanup, and Ending-state identity serialization keep teardown observable and race-safe.
v1.0.32 배포 완료. 권위 있는 exit trigger, crash-recoverable lifecycle journal, 막히지 않는 cleanup, Ending-state identity 직렬화로 teardown을 관측 가능하고 경쟁에 안전하게 유지합니다.
agent session
$ lterm start -d -n codex -- codex created codex %0 $ lterm logs codex --start=-20 sanitized scrollback for review $ lterm resume codex reattached without restarting the agent
Why it exists
왜 쓰나요?
Use tmux for a full multiplexer. Use lterm when agents need a smaller, scriptable persistence layer.
완전한 멀티플렉서가 필요하면 tmux를 쓰면 됩니다. lterm은 에이전트 작업에 필요한 가벼운 세션 유지와 스크립트 자동화에 집중합니다.
tmux-compatible where agents expect it
에이전트 도구가 필요로 하는 tmux 호환성
A focused tmux-compat shim covers the commands common orchestration tools rely on.
오케스트레이션 도구가 자주 쓰는 명령을 tmux-compat shim으로 지원합니다.
Raw attach, safe reports
Raw 연결과 정제된 리포트
Attached PTY bytes stay raw for TUIs. Report surfaces strip terminal controls while preserving UTF-8 text.
TUI가 깨지지 않도록 PTY 연결에서는 바이트를 raw로 전달합니다. 대신 리포트 출력은 터미널 제어 코드를 제거하고 UTF-8 텍스트는 그대로 보존합니다.
Resilient release path
복원력 중심 릴리스
The current release is backed by release preflight, contract checks, upgrade-matrix coverage, and Linux crash-window and managed-process lifecycle tests.
현재 릴리스는 release preflight, contract check, upgrade-matrix coverage, Linux crash-window 및 managed-process lifecycle 테스트로 검증했습니다.
Install
설치
Homebrew and npm are the easiest paths. Cargo from GitHub is useful for source-pinned installs.
Homebrew와 npm이 가장 간편합니다. 소스에서 특정 버전을 고정해 설치하려면 Cargo를 쓰세요.
Homebrew
Recommended on macOS when Homebrew is already your package manager.
macOS에서 Homebrew를 쓰고 있다면 가장 무난한 설치 방법입니다.
brew install ictechgy/tap/lterm
npm
Installs a wrapper plus native platform package on supported macOS/Linux targets.
지원되는 macOS/Linux 환경에서는 래퍼와 네이티브 패키지를 한 번에 설치합니다.
npm install -g @ictechgy/lterm
Cargo
Pin the release tag when installing from source; check GitHub Releases for newer tags.
소스에서 설치할 때는 릴리스 태그를 고정하세요. 최신 태그는 GitHub Releases에서 확인할 수 있습니다.
cargo install --locked --git https://github.com/ictechgy/light_terminal --tag v1.0.32
Quick start
빠른 시작
Create a named session, detach safely, inspect it, then resume when you need the live terminal.
이름을 붙인 세션을 시작하고, 안전하게 분리한 뒤, 필요할 때 다시 실시간 터미널에 연결합니다.
Start a persistent process
계속 실행할 프로세스 시작
lterm start -d -n api -- npm run dev
The process keeps running after your current terminal exits.
현재 터미널을 닫아도 프로세스는 계속 실행됩니다.
Read sanitized scrollback
정제된 scrollback 확인
lterm logs api --start=-80 --end=-1
Good for agents and scripts because terminal controls are stripped from report output.
리포트 출력에서는 터미널 제어 코드를 제거하므로 에이전트와 스크립트가 읽기 쉽습니다.
Resume the live terminal
실시간 터미널에 다시 연결하기
lterm resume api
Compatibility names such as attach, a, and -a remain available.
attach, a, -a 같은 호환 이름도 그대로 쓸 수 있습니다.
Command map
명령어 목록
These are the product CLI commands people and agents usually need first.
사람과 에이전트 모두 먼저 알아두면 좋은 주요 CLI 명령어입니다.
| Task | Command | Compatibility names |
|---|---|---|
| 작업 | 명령 | 호환 이름 |
| Start a persistent process | lterm start -n api -- npm run dev | new |
| 계속 실행할 프로세스 시작 | lterm start -n api -- npm run dev | new |
| Open or create a session | lterm open main | attach-or-new |
| 세션 열기 또는 생성 | lterm open main | attach-or-new |
| Resume a session | lterm resume api | attach, a, -a |
| 기존 세션에 다시 연결 | lterm resume api | attach, a, -a |
| Reconnect to the last selected session | lterm reconnect --mobile | none |
| 마지막으로 선택한 세션에 재접속 | lterm reconnect --mobile | 없음 |
| Review an agent session in mobile scrollback | LTERM_MOBILE=1 lterm resume codex-lterm | Force with --mobile; force raw with --raw |
| 모바일 scrollback에서 agent 세션 확인 | LTERM_MOBILE=1 lterm resume codex-lterm | --mobile로 강제; 기존 raw attach는 --raw |
| Read sanitized scrollback | lterm logs api --start=-80 --end=-1 | capture |
| 정제된 scrollback 확인 | lterm logs api --start=-80 --end=-1 | capture |
| Extract recent URLs | lterm urls api --last | none |
| 최근 URL 추출 | lterm urls api --last | 없음 |
| Search sanitized scrollback | lterm search api 'build failed' | Use /grep QUERY in mobile transcript mode |
| 정제된 scrollback 검색 | lterm search api 'build failed' | 모바일 transcript에서는 /grep QUERY |
| Wait for a marker or exit | lterm wait api --contains READY --timeout 30s --json | none |
| 마커가 나오거나 종료될 때까지 대기 | lterm wait api --contains READY --timeout 30s --json | 없음 |
| Notify on completion | lterm watch api --exit --notify | none |
| 완료 시 알림 | lterm watch api --exit --notify | 없음 |
| Launch an agent profile | lterm codex --name codex-main | agent profiles |
| agent profile 실행 | lterm codex --name codex-main | agent profiles |
| Launch a custom PATH agent | lterm agent grok -- -p 'summarize' | Grok is custom, not a built-in shortcut |
| custom PATH agent 실행 | lterm agent grok -- -p '요약해줘' | Grok은 built-in shortcut이 아닌 custom profile |
| Diagnose local state | lterm doctor --json | status |
| 로컬 상태 진단 | lterm doctor --json | status |
| Inspect redacted diagnostics | lterm inspect --json | same bundle as diagnose --bundle |
| redacted 진단 확인 | lterm inspect --json | diagnose --bundle과 같은 bundle |
Security model in plain language
보안 모델을 쉽게 말하면
lterm is a same-user convenience daemon. It is not a sandbox.
lterm은 같은 OS 사용자 범위 안에서 쓰는 편의 목적의 데몬입니다. 샌드박스가 아닙니다.
Attached terminals are raw. Full-screen apps, shells, and remote PTY streams can emit terminal escape sequences just like they can under tmux or screen.
연결된 터미널은 raw 모드입니다. 전체화면 앱, 셸, 원격 PTY 스트림은 tmux/screen에서와 마찬가지로 터미널 이스케이프 시퀀스를 출력할 수 있습니다.
Mobile reconnect is explicit. lterm reconnect --mobile resumes the last selected local lterm session from a private minimal pointer, falling back to main when the pointer is missing, corrupt, or stale. Preview the reversible SSH-login snippet with lterm init --mobile-reconnect --shell zsh, or omit --shell to detect from $SHELL; lterm never edits shell startup files automatically, and LTERM_RECONNECT_DISABLE=1 skips a copied snippet.
모바일 재접속은 명시적입니다. lterm reconnect --mobile은 비공개 최소 pointer로 마지막으로 선택한 로컬 lterm 세션을 다시 열고, pointer가 없거나 손상됐거나 오래되어 더 이상 맞지 않으면 main으로 fallback합니다. 되돌릴 수 있는 SSH 로그인 snippet은 lterm init --mobile-reconnect --shell zsh로 미리 볼 수 있고, --shell을 생략하면 $SHELL에서 감지합니다. lterm은 shell startup file을 자동 수정하지 않으며, 복사한 snippet은 LTERM_RECONNECT_DISABLE=1로 건너뜁니다.
Reports are sanitized. logs, capture, compose, search, urls, diagnostics, and notification fallback paths strip terminal controls while preserving valid UTF-8 text.
리포트 출력은 정제됩니다. logs, capture, compose, search, urls, 진단, 알림 폴백 경로에서는 터미널 제어 코드를 제거하고 유효한 UTF-8 텍스트를 보존합니다.
Extracted URLs are untrusted. lterm urls helps copy terminal links on small screens, but extracted URLs may include phishing links or short-lived auth/login credentials. It reports at most 256 unique ASCII URL tokens and skips raw candidates over 4096 bytes; in mobile transcript mode, /links and /urls stay local-only. --last prints only the newest valid link, so use it only when you know that link is the one you want.
추출된 URL은 신뢰할 수 없습니다. lterm urls는 작은 화면에서 터미널 링크를 복사할 때 유용하지만, 추출된 URL에는 phishing link나 짧게 살아 있는 인증/login credential이 포함될 수 있습니다. 최대 256개의 unique ASCII URL token만 보고하고, 4096 byte를 넘는 raw candidate는 건너뛰며, mobile transcript의 /links / /urls는 로컬에서만 처리됩니다. --last는 최신 유효 link 하나만 출력하므로, 그 링크가 원하는 링크임을 알 때만 사용하세요.
Agent TUI colors stay independent. Agent launchers do not forward ambient NO_COLOR, FORCE_COLOR, CLICOLOR, or CLICOLOR_FORCE from the client or daemon, while ordinary sessions preserve those variables.
Agent TUI 색상은 분리해 다룹니다. agent launcher는 클라이언트나 데몬에 설정된 NO_COLOR, FORCE_COLOR, CLICOLOR, CLICOLOR_FORCE 환경값을 agent child process에 전달하지 않고, 일반 세션은 이 변수들을 그대로 보존합니다.