Feel Code

AI-powered coding assistant with single-loop architecture, inspired by Claude Code, Codex, Devin, Cursor, and Augment Code.

Core Design Principles

1. Single main loop over multi-agent - Simple while loop, not multi-agent orchestration
2. Build for deletion - Every component is replaceable and isolated
3. Mandatory end-to-end verification - Validation chain on every code change

Architecture

┌─────────────────────────────────────────────────┐
│                   CLI (main.py)                  │
├─────────────────────────────────────────────────┤
│                Agent Loop (Single Thread)         │
│  ┌──────────┐  ┌──────────┐  ┌────────────────┐ │
│  │ Planner  │→ │ Executor │→ │   Validator    │ │
│  └──────────┘  └──────────┘  └────────────────┘ │
│       ↑                            ↓             │
│  ┌────────────────────────────────────────────┐  │
│  │          Self-Correction Engine            │  │
│  │  fix → switch → simplify → human           │  │
│  └────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────┤
│              Context Manager (4 Layers)          │
│  L0: System Prompt │ L1: Project │ L2: Session   │
│  L3: Overflow (filesystem-backed)                │
│  Compression: 60% → 75% → 85% thresholds        │
├─────────────────────────────────────────────────┤
│  Tools (6 core)    │  Skills (SKILL.md)          │
│  bash, file_read,  │  On-demand loading           │
│  file_write,       │  Max 3 active (LRU)          │
│  file_edit, search │  Trigger-based matching       │
│  sub_agent         │                              │
├─────────────────────────────────────────────────┤
│  Memory (3 layers) │  LLM Client                  │
│  Session (volatile) │  OpenAI / Anthropic /        │
│  Project (AGENTS.md)│  OpenAI-compatible           │
│  User (~/.feel-code)│  Hot-switching via factory   │
└─────────────────────────────────────────────────┘

Quick Start

Installation

# Basic install (httpx only)
pip install -e .

# With rich CLI
pip install -e ".[cli]"

# With dev tools
pip install -e ".[dev]"

Configuration

Set your API key:

export FEEL_CODE_API_KEY="your-api-key-here"
export FEEL_CODE_MODEL="gpt-4o"  # or claude-sonnet, deepseek-chat

Usage

Interactive mode:

feel-code
# or specify project directory
feel-code -p /path/to/project

Interactive mode now includes:

• a richer startup dashboard with project, model, tools, skills, and index status
• slash-command completion and history suggestions when prompt_toolkit is installed
• a structured /status view for context pressure, approval state, and understanding status

One-shot mode:

feel-code --prompt "Fix the failing tests in src/"
feel-code --prompt "Summarize the repository architecture" --no-stream

CLI Commands:

Command	Description
/help	Show commands, examples, and tips
/quit	Exit the agent
/status	Show agent state, context load, and indexing
/memory	Show memory across all layers
/skills	List available skills
/clear	Clear session context
/compact	Trigger context compression
/index	Incrementally refresh the project index
/reindex	Rebuild the project index
/understanding [on|off|status]	Inspect or toggle semantic understanding
/approve	Approve a pending high-risk command
/deny	Deny a pending high-risk command

Project Structure

feel-code/
├── feel_code/
│   ├── __init__.py            # Package init, version
│   ├── main.py                # CLI entry point, REPL
│   ├── config/
│   │   ├── settings.py        # AgentSettings dataclass
│   │   └── prompts.py         # System prompts (L0)
│   ├── llm/
│   │   ├── client.py          # Multi-provider LLM abstraction
│   │   └── models.py          # Predefined model configs
│   ├── context/
│   │   ├── layers.py          # 4-layer context architecture
│   │   ├── compressor.py      # 3-level compression engine
│   │   └── manager.py         # Context orchestrator
│   ├── tools/
│   │   ├── base.py            # Tool base class + registry
│   │   ├── bash_tool.py       # Command execution
│   │   ├── file_read.py       # File reading with line numbers
│   │   ├── file_write.py      # File writing with security
│   │   ├── file_edit.py       # Search-and-replace editing
│   │   ├── search.py          # Code search (grep/find/symbol)
│   │   └── sub_agent.py       # Research sub-agent
│   ├── skills/
│   │   ├── loader.py          # SKILL.md discovery + lazy loading
│   │   ├── catalog.py         # Skill activation + LRU lifecycle
│   │   └── builtin/           # Built-in skills
│   ├── agent/
│   │   ├── loop.py            # Main agent loop (state machine)
│   │   ├── planner.py         # Task planning
│   │   ├── validator.py       # Validation chain
│   │   └── self_correction.py # Escalating self-correction
│   └── memory/
│       ├── session.py         # Volatile session memory
│       ├── project.py         # Project-level persistence
│       ├── user.py            # User-level persistence
│       └── manager.py         # Memory orchestrator
├── tests/
├── pyproject.toml
├── README.md
└── AGENTS.md

Key Technical Decisions

Context Management

• 4-layer architecture: L0 (immutable system ~2800 tokens), L1 (project ~4000), L2 (session ~30000), L3 (overflow to filesystem)
• 3-level compression: L1 at 60% (truncation), L2 at 75% (thinking removal), L3 at 85% (LLM summarization)
• KV-Cache optimization: Stable prefix, append-only context, deterministic tool schema serialization

Agent Loop

• State machine: IDLE → PLANNING → EXECUTING → VALIDATING → CORRECTING → COMPLETED/FAILED/WAITING_USER
• Self-correction escalation: fix → switch → simplify → human (with method blacklisting)
• Validation chain: syntax → type check → test run (cost-ascending, short-circuit on failure)

Tool Design

• Core tools + skill activation: Minimal, composable, each with clear security boundaries
• Sub-agent: Read-only research agent with restricted tool access
• Skills: Metadata-first SKILL.md catalog, lazy activation, max 3 concurrent with LRU eviction

Multi-Model Support

• OpenAI (GPT-4o, GPT-4o-mini)
• Anthropic Claude (Sonnet, Haiku)
• OpenAI-compatible (DeepSeek, etc.)
• Hot-switching via create_client() factory pattern

Dependencies

• Core: httpx (only required dependency)
• CLI: rich (formatting), prompt_toolkit (REPL enhancements)
• Dev: pytest, pytest-asyncio, mypy

License

MIT