Cognition AGENTS.md

AGENTS.md — Cognition Coding Agent

Guidelines for agentic coding assistants working on this codebase.

Project Overview

Cognition is an OpenCode-style coding agent with:

• Server: FastAPI WebSocket API with Deep Agents runtime (server/)
• Client: CLI/TUI for interactive sessions (client/)
• Execution: Container-per-session with optional network isolation
• Scope: Python repos only, pytest-based testing

Build / Test / Lint Commands

This project uses uv for dependency management and task execution.

# Install dependencies
uv sync

# Run server (development)
# Runs the FastAPI server with hot reload
uv run uvicorn server.app.main:app --reload --port 8000

# Run client (development)
# Starts the CLI/TUI client
uv run python -m client.cli.main

# Run all tests
uv run pytest

# Run single test file
uv run pytest tests/unit/test_settings.py -v

# Run single test case
uv run pytest tests/unit/test_settings.py::TestSettingsDefaults::test_default_server_settings -v

# Type checking (Strict)
uv run mypy .

# Linting & Formatting (Ruff)
uv run ruff check .
uv run ruff format .

Code Style Guidelines

Python Standards

• Python 3.11+ required.
• Type Hints: strict mypy compliance. Use from __future__ import annotations.
• Docstrings: Google style for all public functions/classes.
• Line Length: Follow ruff config (default 88/100).
• Imports: Grouped as stdlib, third-party, local. Use absolute imports.

Naming Conventions

• snake_case: functions, variables, modules.
• PascalCase: classes, types.
• UPPER_CASE: constants.
• _prefix: private methods/attributes.
• async functions: often prefixed with verbs like get_, fetch_, handle_.

Async Patterns

• Async/Await: Use for all I/O operations (DB, Network, File).
• Concurrency: Use asyncio.gather() for parallel independent tasks.
• Subprocesses: Use asyncio.create_subprocess_exec.

Error Handling

• Exceptions: Use custom hierarchy in server/app/exceptions.py.
• Pattern: Catch external errors -> Raise domain-specific CognitionError.
• Logging: Log errors before raising if context is needed, otherwise let middleware handle it.