Cypraea/DESIGN.md

Cypraea

Overview

Cypraea is a Bash-compatible shell implemented as a client-server architecture with a focus on persistent sessions, robust command execution, and extensive logging. It is designed not only as a shell but as an observability and behavioral insight tool for terminal usage.

The goal is to provide infrastructure for:

1. Persistent, resumable shell sessions.
2. Detailed logging of all commands, including timing, results, and output.
3. Analysis of command behavior for ML systems, diagnostics, and real-time assistance.

Cypraea draws architectural inspiration from tmux and semantic goals from observability and telemetry systems.

Goals

• Bash-compatible command behavior
• Client-server architecture
• Session-based shell state management
• Commands persist through disconnects (like SSH dropouts)
• Real-time command streaming and output
• Comprehensive, always-on command logging
• Future capability for behavioral analysis and assistance

Core Architecture

Cypraea consists of:

• A daemon process (cypraeadd) running per user, managing all sessions.
• A client frontend (cypraea) that connects to the daemon and attaches to a session.
• Communication over a Unix domain socket using line-delimited JSON.

The daemon is responsible for:

• Managing named shell sessions
• Executing commands
• Capturing and streaming stdout/stderr
• Logging metadata and command output
• Retaining session state (cwd, env, aliases, etc.)

Sessions

• Sessions are per-user but multiple per user (like tmux).
• Each session is identified by a numeric or later symbolic name.
• Sessions contain their own state:
  • Current working directory
  • Environment variables
  • Aliases and other shell-local information
• Sessions are created automatically when referenced.
• Clients attach to sessions and may disconnect without terminating them.

Client-Server Communication

• Communication happens over a Unix domain socket, at $XDG_RUNTIME_DIR/cypraea.sock.
• Only accessible by the user, controlled via file permissions.
• Messages are newline-delimited JSON, encoded in UTF-8.

Example Request (client → server):

{ "type": "run_command", "session": "1", "cmd": "ls -la", "cwd": "/tmp", "env": { "FOO": "bar" } }

Example Response (server → client):

{ "type": "stdout", "data": "file1.txt\n" }
{ "type": "stderr", "data": "warning: something\n" }
{ "type": "exit", "code": 0 }

• Output is streamed in real time.
• Messages may be chunked arbitrarily.

Command Execution

• Commands are run using tokio::process::Command.
• stdout and stderr are piped back to the client in real time.
• Command output is also captured for logging.
• Execution occurs within the context of the session (cwd, env, etc.).
• Support for concurrent execution of commands across sessions and clients.

Logging System

• Logs are stored in a SQLite database at $XDG_DATA_HOME/cypraea/log.sqlite.
• Every command execution is logged, including:
  • Timestamps (start/end)
  • Duration
  • Command text
  • Working directory
  • Environment (optional, partial)
  • Exit code
  • stdout and stderr output

Example table schema:

CREATE TABLE commands (
  id INTEGER PRIMARY KEY,
  session TEXT,
  timestamp_start DATETIME,
  timestamp_end DATETIME,
  duration_ms INTEGER,
  cmd TEXT,
  cwd TEXT,
  exit_code INTEGER,
  stdout TEXT,
  stderr TEXT
);

• Logging is always on.
• Output size may be truncated or compressed in future versions.
• No retention or cleanup policy yet (by design).

Security

• Access to the daemon is limited to the user by standard Unix file permissions.
• No multi-user access is allowed or supported.
• Future: socket authentication and encryption can be explored.

Implementation Stack

• Language: Rust
• Async Runtime: Tokio
• IPC: Unix domain sockets via tokio::net::UnixStream
• Message Serialization: serde_json
• Command Parsing: shell-words
• Logging: SQLite using rusqlite

Future Ideas

• Terminal emulator integration or attach/detach model
• Web dashboard or analytics viewer
• Error recognition and command recommendations
• LSP integration for intelligent shell completions
• Integration with OpenTelemetry or observability pipelines
• Plugin system and event hooks

Summary

Cypraea is a shell for users and systems that want to learn from what happens at the command line. With real-time execution, logging, and stateful sessions, it serves as a durable, intelligent layer between user behavior and system insight.