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):

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

Example Response (server → client):

```json
{ "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:

```sql
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.