feat: add standalone CLI for cross-agent PTY management #5
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Introduces pty-skill CLI that works with Claude Code, Codex CLI, and other AI agents without requiring MCP server context pollution. Architecture: - Extract shared core (manager, buffer, types) to src/core/ - Unix socket daemon for session persistence across CLI calls - JSON-RPC protocol for client-daemon communication - Auto-start daemon on first CLI invocation CLI commands: - spawn: Start background PTY sessions - read: Read output with pagination and regex filtering - write: Send input with escape sequence support - list: List all sessions with status - kill: Terminate sessions with optional cleanup - status: Check daemon status - daemon: Manage daemon (start/stop/restart/logs) Also includes: - SKILL.md with comprehensive usage documentation - Build system for platform binaries (darwin-arm64, darwin-x64, linux-x64) - Updated GitHub workflow to build and upload release binaries - Package renamed to pty-skill with bin entry The existing OpenCode plugin continues to work alongside the CLI.
- Prerequisites and setup instructions - Running CLI directly from source - Three options for installing as a Claude Code skill - Instructions for symlinking SKILL.md to ~/.claude/skills/ - Building binaries for distribution - Project structure overview
- Skills require subdirectory structure (~/.claude/skills/pty-skill/) - Add Dependencies section to SKILL.md with install instructions - Update README with correct symlink instructions
- Add examples/claude-code-conversation.md showing nvim interaction - Link to example from README
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a standalone CLI tool (
pty-skill) that enables any AI agent to manage interactive PTY sessions, not just OpenCode. The CLI works with Claude Code, Codex CLI, and other AI tools without requiring MCP server configuration (which would pollute context on every message).Motivation
The current plugin only works with OpenCode. Many AI agents (Claude Code, Codex CLI, etc.) need to interact with long-running processes but lack this capability. An MCP server approach was considered but rejected because tool definitions would be included in every message, consuming tokens even when unused.
The CLI + Skill approach solves this:
Changes
Architecture
src/core/) from plugin codeNew Files
cli/- Complete CLI implementation (daemon, client, commands)src/core/- Shared core (manager, buffer, types, logger)SKILL.md- AI agent skill documentation with triggersbuild-cli.ts- Build script for platform binariesexamples/claude-code-conversation.md- Real usage exampleCLI Commands
Package Changes
pty-skill(more descriptive for cross-agent use)binentry for CLIBackward Compatibility
src/core/instead of duplicated codeTesting
examples/claude-code-conversation.md)