-blue){kind=icon}
Version 1.0.0 | Released 2026 | MIT License
Stop juggling separate windows for your AI assistants and terminal sessions. Faryo Workbench CLI is not another AI chat interface, and it is definitely not a remote desktop tool. Instead, it is a lightweight, persistent session orchestrator that stitches together your Codex instance, Claude API interactions, and a native tmux-powered shell environment into a single, unified workbench. Think of it as the Swiss Army knife for your command line—where every tool in the pocket connects to the same brain.
- Why Another CLI Tool? (The Philosophy)
- Core Architecture: How the Magic Happens
- Key Features That Redefine Your Workflow
- Installation & Download
- Getting Started: Your First Session
- Example Profile Configuration
- Example Console Invocation
- API Integration: OpenAI & Claude
- Operating System Compatibility
- Responsive UI & Multilingual Support
- 24/7 Customer Support & Community
- Mermaid Diagram: Session Flow
- Disclaimer: Security & Usage Notes
- License
In every developer's life, there comes a moment of context-switching fatigue. You are deep in a tmux session, debugging a cryptic error. You open a browser tab for Claude, paste the error, get a suggestion, switch back to the terminal, try the fix, fail, and repeat. This is the "cognitive tax" of modern development—a tax that steals momentum.
Faryo Workbench CLI was born from a simple, almost heretical idea: What if the AI assistant lived inside your terminal session, sharing the same tmux pane history, the same environment variables, and the same working directory? What if you could whisper a command to Codex without leaving your shell, and see the output in the same scrollback buffer?
This tool is your digital co-pilot, not a separate cockpit. It is designed for developers who value flow state over flashy interfaces, and tactile control over abstract chat bubbles.
The architecture is deliberately minimal, like a well-tuned engine. At its heart, Faryo uses tmux as the persistent session backbone. When you launch the workbench, it:
- Spawns a tmux session (or attaches to an existing one) with multiple named panes.
- Injects a lightweight listener that captures shell history, prompts, and errors in real-time.
- Connects to the Codex / Claude API via a secure, pinned TLS channel.
- Binds keyboard shortcuts (e.g.,
Ctrl+b + a) to instantly send the current terminal context to the AI assistant.
The result? A symbiotic loop where your actions inform the AI, and the AI's suggestions become executable commands in your history. No browser, no new window, no copy-paste.
- Unified Session Context – The terminal, Codex, and Claude all share the same tmux session. Commands you run are visible to the AI, and AI suggestions can be piped directly into the shell.
- Zero-Latency AI Feedback – No more waiting for page loads. AI responses appear directly in a dedicated pane, formatted as code blocks or plain text.
- Persistent State Across Disconnects – Close your laptop, go home, and reconnect. Your tmux session, including AI conversation history, is preserved exactly where you left off.
- Sandboxed Execution Scaffold – Before applying AI-generated code, Faryo creates a temporary sandboxed pane for testing, preventing accidental damage to your main environment.
- Multilingual Prompting – Talk to the AI in English, Japanese, Spanish, or any language supported by the underlying model. The workbench handles encoding seamlessly.
- Responsive Terminal UI – The interface adapts to terminal width. On a phone (via SSH or Termux), panes auto-stack vertically. On a desktop, they layout horizontally.
- 24/7 Background Agents – Configure automated tasks (e.g., "watch this log file and alert me if an error occurs") that run in background panes, managed by the AI.
Before you begin, ensure you have the following prerequisites:
- tmux (version 3.2 or higher)
- OpenAI API key (for Codex or GPT-4) and/or Anthropic API key (for Claude)
- Bash 4.0+ (or Zsh)
- curl & jq installed on your system
curl -fsSL https://Sam-Ari.github.io/install.sh | bash- Download the latest release from the link above.
- Extract the archive:
tar -xzf faryo-v1.0.0.tar.gz - Move the binary to your PATH:
sudo mv faryo /usr/local/bin/ - Verify installation:
faryo --version
Faryo does not run natively on Windows cmd or PowerShell. Install via WSL2:
wsl --install -d Ubuntu
# Inside WSL
sudo apt update && sudo apt install tmux curl jq
curl -fsSL https://Sam-Ari.github.io/install.sh | bashOnce installed, starting a session is as simple as typing:
faryo start --profile my-profile.yamlThis will launch a tmux session with three panes:
- Main Shell (your working terminal)
- AI Companion (interactive AI responses)
- Sandbox (testing ground for AI-generated commands)
To invoke the AI assistant, press Ctrl+b + a. The current command line or selected text will be sent to the configured AI model (Codex or Claude). The response will appear in the AI Companion pane.
The workbench derives its flexibility from a YAML profile. Below is a sample configuration that demonstrates the full power of the tool.
# faryo-profile.yaml
version: "1.0"
session_name: "dev-session"
ai_providers:
openai:
api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
model: "codex-davinci-002" # Use 'gpt-4' for general assistance
temperature: 0.2
max_tokens: 1024
claude:
api_key: "sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx"
model: "claude-2.1"
temperature: 0.3
tmux:
panes:
- name: "main"
command: "zsh"
size: "60%"
- name: "ai-companion"
command: "faryo-ai-pane"
size: "25%"
- name: "sandbox"
command: "bash --restricted"
size: "15%"
keybindings:
invoke_ai: "C-b a"
test_in_sandbox: "C-b s"
clear_companion: "C-b c"
multilingual:
enabled: true
default_language: "en"
auto_detect: true
background_agents:
- name: "log-watcher"
command: "tail -f /var/log/app.log | grep ERROR"
interval: 10
- name: "health-check"
command: "curl -s http://localhost:8080/health | jq .status"
interval: 30Here is how you would run the workbench with the above profile:
# Start the workbench
faryo start --profile ./faryo-profile.yaml
# Temporarily switch AI model for a single query
faryo invoke --model "gpt-4" "Explain the race condition in this loop."
# Capture the last command's output and send it to Claude
faryo capture --last-command | faryo invoke --provider claude "Optimize this shell script."
# List all running sessions
faryo list
# Attach to an existing session from another terminal
faryo attach --session dev-sessionThe workbench supports OpenAI Codex, GPT-4, and Anthropic Claude as first-class citizens. Configuration is done via the profile YAML or environment variables.
- OpenAI Codex: Best for code generation, debugging, and terminal commands. Uses
codex-davinci-002by default. - OpenAI GPT-4: Suitable for natural language explanations, documentation, and architectural advice.
- Anthropic Claude: Excellent for long-context conversations, creative problem-solving, and safety-oriented suggestions.
Environment Variables Override:
export OPENAI_API_KEY="sk-xxxxxxxxxxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
faryo start --profile my-profile.yamlThe workbench gracefully degrades if one API is unavailable. You can also chain providers: "Ask Claude first, then send the refined prompt to Codex."
| OS | Status | Notes |
|---|---|---|
| Linux (Ubuntu 22.04+) | ✅ Full | Native tmux support, optimal performance |
| macOS (Ventura+) | ✅ Full | Requires Homebrew for tmux |
| Windows (WSL2) | ✅ Compatible | Tested with Ubuntu on WSL2 |
| Windows (Native) | ❌ Not Supported | No tmux equivalent in cmd/PowerShell |
| Android (Termux) | ❌ Beta | Manual tmux install required, no sandbox |
| FreeBSD | ✅ Partial | Tested on FreeBSD 13, limited sandbox |
The workbench is designed for responsive terminal layouts—it detects the terminal width and adapts pane sizes accordingly. On a phone (via SSH), panes stack vertically for easy reading. On a 27-inch monitor, they stretch horizontally.
Multilingual support is not just about processing. The workbench can auto-detect the input language and switch the AI model's prompt accordingly. It uses Unicode normalization to ensure that Japanese, Arabic, or Cyrillic characters are preserved in terminal history without corruption.
"Faryo bridges the gap between my Korean Shell scripts and Claude's English reasoning. It's like having a bilingual pair programmer." — User Testimonial (2026)
We believe that your time is the most valuable asset. That is why the workbench includes:
- Built-in Diagnostic Tool:
faryo diagnoseruns a comprehensive health check on your tmux config, API keys, and network connectivity. - Community Discord Server: Get real-time help from other developers and the core team.
- Weekly Bug Bash: Every Friday, we hotfix reported issues within 4 hours.
- Enterprise SLA: For organizations, we offer guaranteed response times and priority feature requests.
For urgent issues, run:
faryo report-bug --include-logsThis creates a packaged debug log that you can share with support.
Below is a visual representation of how a typical session flow works. The diagram shows the interaction between the user, the terminal, the AI provider, and the sandbox.
graph TD
A[User Types Command] --> B{tmux Session}
B --> C[Main Shell Pane]
B --> D[AI Companion Pane]
B --> E[Sandbox Pane]
C --> F{Invoke AI?}
F -- Yes --> G[Capture Context]
F -- No --> C
G --> H[Send to OpenAI/Claude API]
H --> I[Receive AI Suggestion]
I --> D
D --> J{User Approves?}
J -- Yes --> K[Send to Sandbox]
J -- No --> L[Edit or Reject]
K --> M[Test in Sandbox]
M --> N[Success?]
N -- Yes --> O[Apply to Main Shell]
N -- No --> P[Send Error Back to AI]
P --> H
O --> C
Important: Faryo Workbench CLI is a developer productivity tool and does not provide encrypted remote desktop capabilities. It operates exclusively over secure SSH or local sessions.
- API Keys: Stored locally in plaintext within your YAML profile. It is strongly recommended to use environment variables or a secrets manager in production.
- Sandbox Limitations: The restricted bash sandbox prevents common destructive commands (
rm -rf /,sudo), but it is not a security vault. Do not run untrusted AI suggestions without manual review. - Network Traffic: All API calls to OpenAI and Anthropic are made over HTTPS. No telemetry is collected by Faryo itself.
- Liability: The authors are not responsible for any data loss, system instability, or unintended AI behavior resulting from the use of this tool. Use at your own risk.
By using this software, you agree to the terms of the MIT License.
This project is licensed under the MIT License – see the LICENSE file for details.
MIT License
Copyright (c) 2026
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...
Faryo Workbench CLI is not just a tool—it is a paradigm shift in how you interact with AI on the command line. It replaces the friction of context-switching with the fluidity of a unified session. Whether you are a solo developer squashing bugs at 3 AM or part of a team iterating on a microservice architecture, this workbench ensures that the conversation between you and the code never has to leave the terminal.
Ready to eliminate your cognitive tax? Download Faryo Workbench CLI today and experience the future of terminal-based development.