This project proposes a terminal-based user interface (TUI) application, built entirely in JavaScript using a modern runtime such as Node.js, that functions as a secure, extensible harness for large language models. Designed for developers and advanced users, the system provides a unified keyboard-driven interface for handling both ad-hoc conversational queries and automated multi-step task execution. Rather than operating as a simple chat wrapper, the application serves as an intelligent workflow coordinator that can chain tool invocations, manage session state, and maintain context across long-running operations. The entire experience is optimized for terminal-native interaction, ensuring fast, scriptable, and reproducible workflows that integrate cleanly with existing command-line environments.
The harness incorporates a centralized tool and skills registry that enables the LLM to interact with both local and remote systems through a standardized, extensible interface. Skills are organized into dedicated directories named after the skill using lowercase, hyphenated identifiers, with all related execution assets stored in a nested scripts subdirectory. Local capabilities include filesystem manipulation, process management, environment variable handling, and host machine queries, while remote capabilities cover API orchestration, web services, cloud integrations, and networked data exchange. Each registry entry defines precise input schemas, output contracts, execution contexts, and permission scopes. Users, external developers, and the harness itself may dynamically register new skills through configuration files, plugin endpoints, or runtime discovery mechanisms. All newly defined skills undergo schema validation and capability scoping before activation, ensuring that extended functionality remains secure, predictable, and fully auditable without compromising the core system boundaries.
Context and long-term memory are managed through a transparent, file-based system using markdown documents. Conversation history, tool outputs, user-supplied context, and execution logs are persisted as plain text markdown files, enabling version control, cross-session recall, and full human-readable auditability. Personality and operational guidelines are defined in a dedicated configuration file named SOUL.md, which establishes the assistant’s tone, expertise domains, behavioral constraints, and default decision-making patterns. Both the memory files and SOUL.md are fully user-definable and can be edited externally or through the interface, but the system ships with secure, opinionated defaults to guarantee safe out-of-the-box behavior and prevent unintended model drift.
To minimize risk and ensure execution reproducibility, all LLM inference, skill execution, and state management operate within a strictly isolated runtime environment. The RTE is engineered to support both Node.js and Python, allowing skills and their associated scripts to execute natively in their preferred language while enforcing consistent security and isolation guarantees. Execution is sandboxed through process boundaries, capability restrictions, and controlled filesystem/network access, preventing unintended interaction with the host environment or sensitive data. The harness is designed for containerized deployment, typically via Docker, which packages the RTE and application logic into a reproducible artifact without implying nested execution. Memory directories and configuration files are mapped as selectively writable paths, allowing users to maintain persistence while preserving execution immutability. This architecture guarantees that unexpected model behavior, tool misconfigurations, or adversarial prompts remain fully contained within the isolated execution context, making the system suitable for both local development and execution of untrusted or high-stakes tasks.
The application is designed to support multiple interaction modes, including interactive conversational mode, non-interactive batch execution, and pipeline-friendly output formatting for scripting and automation. All system configuration is centralized in a single config.yaml file located in the project root directory, leveraging YAML syntax to ensure high readability for both end users and the harness itself. The configuration schema explicitly supports popular cloud AI LLM providers, OpenAI-compatible API endpoints, local model deployments, and custom cloud resources that expose standardized REST or WebSocket interfaces. Provider entries include structured fields for base URLs, model identifiers, authentication credentials, rate limits, temperature settings, and fallback routing rules. The harness also includes built-in support for OpenTelemetry (OTEL), providing standardized distributed tracing and metrics collection across all LLM interactions, skill executions, and sandbox operations. Telemetry data is exported via native OTEL protocols to configurable endpoints, enabling seamless integration with existing observability stacks, log aggregation platforms, and performance monitoring dashboards. All tracing spans and metric definitions are structured to capture token usage, latency, tool execution costs, error rates, and memory persistence states, while strictly adhering to the execution environment’s security and network boundaries. Telemetry configuration is managed alongside other system settings in config.yaml, allowing users to define export formats, sampling rates, endpoint URLs, and redaction policies for sensitive data. The harness retains the ability to programmatically modify its own configuration settings at runtime, enabling dynamic adjustment of sandbox parameters, memory retention policies, skill permissions, scheduling rules, active provider assignments, and telemetry export behaviors without requiring manual intervention or service restarts. The system also includes a built-in cron scheduler that enables automated, time-based execution of registered skills. Users can define recurring tasks, system health checks, data synchronization routines, or proactive monitoring workflows through declarative schedule configurations. Each scheduled execution inherits the harness’s security boundaries, memory context, and skill permissions, running deterministically within the isolated execution context and logging results to the persistent markdown store. All configuration, memory, and personality definitions are externalized into plain-text files, making the system version-controllable, easily shareable, and portable across environments. By combining a deterministic execution model, transparent markdown-backed memory, strict sandboxing, and user-controlled personality definitions, the harness delivers a powerful, auditable, and secure foundation for LLM-driven task automation that prioritizes user control, reproducibility, and security over opaque black-box behavior.
The development lifecycle enforces a strict phase-gated validation process backed by comprehensive unit and integration testing. Each implementation phase must include a complete test suite covering core functionality, tool execution paths, memory persistence, sandbox isolation, and interface responsiveness. Unit tests verify internal logic, state transitions, and component contracts, while integration tests validate cross-module interactions, end-to-end workflows, and sandbox boundary enforcement. No phase may proceed to the next stage until all associated unit and integration tests pass with full coverage and deterministic results. This mandatory gatekeeping mechanism ensures architectural integrity, prevents regression, and maintains a stable, production-ready codebase throughout the entire development cycle.