cortex

Imported from tky0065/cortex (AGENTS.md). Install upstream with npx skills add tky0065/cortex. Copyright stays with the author.

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Commit conventions

Never add Co-Authored-By: Codex Sonnet 4.6 <noreply@anthropic.com> (or any Codex co-author line) to commit messages.

What is Cortex

Cortex is an agentic CLI written in Rust that simulates a full software development company. Given a single natural-language idea, it orchestrates six specialized AI agents (CEO → PM → Tech Lead → Developer → QA → DevOps) to produce a complete, deployable Git repository.

It runs like Codex or opencode: a REPL by default (cortex), with slash commands (/start, /status, /abort), and a one-shot mode (cortex start "<idea>" --auto).

Full product specification: product-development/current-feature/PRD.md

Commands

cargo build                    # compile
cargo run                      # run the CLI
cargo check                    # fast type/borrow check (use this often)
cargo test                     # run all tests
cargo test <test_name>         # run a single test
cargo clippy -- -D warnings    # lint (treat warnings as errors)
cargo fmt                      # format

Implementation Status

Files currently implemented:

• src/main.rs, src/config.rs, src/orchestrator.rs, src/repl.rs
• src/workflows/{mod,dev/mod,marketing/mod,prospecting/mod}.rs
• src/workflows/dev/agents/{mod,ceo,pm,tech_lead,developer,qa,devops}.rs
• src/workflows/dev/prompts/{ceo,pm,tech_lead,developer,qa,devops}.md
• src/workflows/marketing/agents/{mod,strategist,copywriter,analyst,social_media_manager}.rs
• src/workflows/marketing/prompts/{strategist,copywriter,analyst,social_media_manager}.md
• src/workflows/prospecting/agents/{mod,researcher,profiler,copywriter,outreach_manager}.rs
• src/workflows/prospecting/prompts/{researcher,profiler,copywriter,outreach_manager}.md
• src/tui/{mod,layout,events}.rs
• src/tui/widgets/{mod,input,pipeline,agent_panel,logs}.rs
• src/tools/{mod,filesystem,terminal}.rs
• src/providers/{mod,ollama}.rs
• src/context/mod.rs
• src/context/mod.rs

Architecture

Current and planned src/ structure:

src/
  main.rs                    # ✅ CLI entry: clap + routing --workflow <name>
  repl.rs                    # ✅ Slash commands dispatcher (/start, /status, /abort, /help, /config, /logs, /apikey, /websearch)
  config.rs                  # ✅ ~/.cortex/config.toml — models, limits, profile
  orchestrator.rs            # ✅ Generic orchestrator over dyn Workflow
  tui/
    mod.rs                   # ✅ Tui struct: setup/teardown, async event loop (tokio select!)
    layout.rs                # ✅ 4-zone layout: pipeline, agents, logs, input, status
    events.rs                # ✅ TuiEvent channel (AgentStarted, TokenChunk, AgentDone…)
    widgets/
      mod.rs                 # ✅
      pipeline.rs            # ✅ Dynamic agent status bar (✓ ● ◌ ✗)
      agent_panel.rs         # ✅ Per-agent live block + progress bar
      logs.rs                # ✅ Scrollable timestamped log panel
      input.rs               # ✅ tui-input command bar with cursor
  workflows/
    mod.rs                   # ✅ Workflow trait + get_workflow() registry
    dev/                     # Software development workflow
      mod.rs                 # ✅ DevWorkflow stub
      agents/{ceo, pm, tech_lead, developer, qa, devops}.rs
      prompts/<role>.md
    marketing/               # Marketing & content workflow
      mod.rs                 # ✅ MarketingWorkflow stub
      agents/{strategist, copywriter, social_media_manager, analyst}.rs
      prompts/<role>.md
    prospecting/             # Freelance outreach workflow
      mod.rs                 # ✅ ProspectingWorkflow stub
      agents/{researcher, profiler, copywriter, outreach_manager}.rs
      prompts/<role>.md
  tools/
    mod.rs
    filesystem.rs            # Sandboxed read/write (path-traversal blocked)
    terminal.rs              # Allowlisted command execution
    web_search.rs            # Brave Search API — fetch_context() injects results into every agent prompt
    email.rs                 # SMTP tool — dry-run by default, --send explicit
  context/
    mod.rs                   # Selective context injection per agent
    compressor.rs            # Summary compression for long outputs
  providers/
    mod.rs
    ollama.rs                # Local Ollama (OpenAI-compat)
    openrouter.rs            # Remote fallback

Key Dependencies

Critical Design Constraints

Context window safety: Never pass the full accumulated transcript to downstream agents. Each agent reads only its required input documents from disk (specs.md, architecture.md) — this is the file-as-memory pattern. Context budget per agent call is configurable in config.toml.

Terminal tool security: The terminal MCP tool must validate every command against a hardcoded allowlist (cargo, go, npm, pip, git, docker) before execution. Commands are built from LLM output — treat them as untrusted input.

Filesystem sandbox: All file reads/writes are restricted to the project output directory. Validate paths to reject ../ traversal before any std::fs call.

QA ↔ Developer loop: Has a hard cap (max_qa_iterations, default 5). Track iteration count in the orchestrator state, not inside the agents.

Agent Workflow

User idea → [CEO] → [PM: specs.md] → [Tech Lead: architecture.md]
         → [Developer: source files] ↔ [QA: tests + bug reports] (loop)
         → [DevOps: Dockerfile, docker-compose, git commit]
         → Final report

In --interactive mode the workflow pauses after specs.md, architecture.md, and the first passing build for user validation.

Web Search

When config.tools.web_search_enabled = true and api_keys.web_search is set, every call to providers::complete() automatically:

1. Extracts the first ~200 chars of the agent's prompt as a search query
2. Calls tools::web_search::fetch_context(query, config) (Brave Search API)
3. Appends a ## Web Search Results Markdown block to the prompt before the LLM call

All 18 agent system prompts include a ## Web Search instruction to use these results.

REPL commands:

/apikey web_search <key>   # store Brave Search API key in config
/websearch enable          # activate (saved to ~/.cortex/config.toml)
/websearch disable         # deactivate
/websearch                 # show current status

Injection point: src/providers/mod.rs → complete() — no individual agent files need to change when adding web search to a new workflow.

Configuration File

User config lives at ~/.cortex/config.toml:

[provider]
default = "ollama"

[models]
ceo       = "ollama/qwen2.5-coder:32b"
developer = "ollama/qwen2.5-coder:32b"
qa        = "ollama/qwen2.5-coder:14b"

[limits]
max_qa_iterations = 5
max_tokens_per_call = 8192

[tools]
web_search_enabled = false  # enable with /websearch enable in the REPL

[api_keys]
# web_search = "BSA..."     # Brave Search API key — set with /apikey web_search <key>

DOCUMENTATION

• Updated README.md and site if we added new features or changed usage instructions.