oly: A Persistent Session Management Tool for AI Agents and Interactive CLIs

This article introduces oly—a persistent session management tool designed specifically for AI agent workflows and automated tasks requiring human intervention. It addresses the problems of traditional terminal sessions being prone to interruption and existing tools lacking integration. Its core value lies in transforming interactive CLI workflows into monitorable, persistent services, supporting terminal detachment, log auditing, remote input, and reconnection at any time.

Background

In today's era of widespread AI agents and automation, developers often face challenges in managing long-running interactive CLI tasks: closing a traditional terminal session or losing network connection terminates the process, while tools like tmux/screen lack sufficient integration with AI agents, remote management capabilities, and fine-grained input control. oly was born to fill this gap.

Design Philosophy

oly is centered on the concept of "session as a service", upgrading terminal sessions into managed persistent service entities. It provides lifecycle management, status monitoring, input/output redirection, and audit tracking capabilities, adapting to scenarios such as AI coding agents, installation programs requiring human confirmation, and team collaboration supervision.

1. Terminal Detachment & Process Daemon: Breaks the binding between terminal and session; processes continue running after the terminal is closed, and buffered output is replayed upon reconnection.
2. Intelligent Input Detection & Notifications: Blocks and waits for input prompts via logs --wait-for-prompt, and triggers external alerts through notification hooks.
3. Flexible Input Control: Supports text, special keys (e.g., Ctrl+C), and raw byte sequences; allows precise process control without attaching to the session.
4. Built-in Web Control Plane: Local HTTP service + Web UI for session management via browser; remote management requires a secure tunnel or reverse proxy.
5. Federated Node Management: Multi-node federated architecture; the main node can monitor sessions on multiple worker nodes, supporting cross-machine collaboration and distributed AI deployment.

Installation Methods

• Package Managers: npm (npm i -g @slaveoftime/oly), Cargo (cargo install oly), Homebrew (macOS-exclusive tap).
• Precompiled Binaries: GitHub Releases offers versions for macOS Apple Silicon, Linux x86_64, and Windows x86_64.

Typical Workflows

1. AI Agent Supervision: Detach after starting an AI coding agent; wait for intervention opportunities via logs --wait-for-prompt, then send commands and continue running in the background.
2. Log Auditing: View the last N lines of output, remove color codes, or access full logs; all outputs are persistently stored to form an audit trail.
3. Remote Collaboration: Via federated features, team members can collaborate across machines to supervise tasks; the main node can view status, send inputs, or stop tasks.

Technical Architecture

• PTY Management: Handles the creation and management of pseudo-terminals in depth, ensuring processes get the correct terminal environment while intercepting and redirecting input/output.
• State Persistence: Uses SQLite to store session metadata and the file system to store logs; the state directory follows OS standard specifications and supports custom locations.

Security Design

• The HTTP service is bound to the local loopback address by default and enables password authentication.
• It is recommended to expose the Web interface via external security gateways (e.g., Cloudflare Access, Tailscale, SSH tunnels) to avoid direct public network access.

Ecosystem Integration

oly is compatible with mainstream AI coding tools such as GitHub Copilot CLI, Claude Code, Gemini CLI, and OpenCode; it provides machine-readable output via oly ls --json for easy script integration.

Applicable Scenarios

• AI coding agent developers: Keep agents running in the background and intervene at the right time.
• DevOps personnel: Execute database migrations or system updates that require mid-process confirmation.
• Data scientists: Run time-consuming model training or data processing scripts.
• Small teams: Lightweight task supervision and collaboration infrastructure.
• Any scenario requiring conversion of interactive CLI into a manageable service.

Summary

oly provides an elegant solution for workflow management in the AI agent era by upgrading terminal sessions into persistent services. It balances simplicity with rich functionality, local-first with federated expansion, and security with convenience, and will become an important infrastructure in the field of AI agent applications.

Resources

The project provides detailed documentation: Product Specification (SPEC.md), System Architecture (ARCHITECTURE.md), PTY Behavior Details (ARCHITECTURE_PTY.md), and Operation Notes (ARCHITECTURE_NOTES.md) to help users use the tool and developers contribute.