.cursorrules

Below is a concise guide explaining the Cypher Core codebase:

1. **Project Structure**:
   - `src/agents`: Contains agent classes extending `BaseAgent` and defining their behavior.
   - `src/models`: Houses model clients (OpenAI, Anthropic, Fireworks) and adapters that normalize their inputs/outputs.
   - `src/features`: Contains feature modules that add new terminal commands (tools) for the agent.
   - `src/terminal`: Handles command parsing, execution logic, and registry.
   - `terminalCore.ts`: Manages a loop running the agent continuously and applying features.
   - `config/agent.yaml`: Defines agent personality, banned phrases, and other configuration details.
   - `index.ts`: Entry point for initializing and running the system (including Logger Server and TerminalCore).

2. **BaseAgent**:
   - Manages chat history and communicates with model clients.
   - Can produce structured outputs (via Zod schemas) or call tools (via function calling).
   - Define tools in `protected defineTools()` to give the agent new capabilities.

3. **Model Adapters & Clients**:
   - Adapters standardize model interactions.
   - Clients connect to external services like OpenAI, Anthropic, or Fireworks.
   - Switch model backends easily without rewriting agent logic.

4. **Tools (Function Calling)**:
   - Agents can call defined tools (functions) with parameters specified by JSON schemas.
   - Tools let the agent perform actions like searching the web or running terminal commands.
   - Add new tools by creating a `Tool` object and registering it in an agent’s `defineTools()`.

5. **TerminalCore & Features**:
   - `TerminalCore` runs an agent in a loop, acting as a world interface (like a terminal).
   - Features add commands to the terminal environment that the agent can invoke.
   - Add a new feature by creating a `TerminalFeature` that returns `Command[]` objects and pass it to `TerminalCore`.

6. **GUI & Logging**:
   - A built-in GUI (via `loggerServer.ts`) shows logs, system prompts, and chat history in real-time.
   - Use `Logger.enable()`, `Logger.disable()`, and `Logger.setLevel('debug')` to control log verbosity.

7. **Adding a Feature**:
   - Create a `.ts` file in `src/features/` that exports a `TerminalFeature`.
   - Implement `loadFeatureCommands()` to return an array of `Command` definitions.
   - Register it in the `TerminalCore` options.

8. **Workflow**:
   - Start with a base agent, define personality and goals.
   - Add tools or structured output schemas as needed.
   - Run the agent via `TerminalCore` for autonomous operation.
   - Observe behavior in the GUI and iterate.

This high-level overview should make it easy to add features or help improve the Cypher Core system.