fecode-cli

v1.1.1

Published

a day ago

FeCode - Interactive Terminal Coding Assistant

0High
0Medium
0Low

Overview

FeCode is an interactive, terminal-native AI coding assistant built for developers who want the velocity of LLM-assisted programming without surrendering control of their workspace.

Unlike traditional AI assistants that execute commands or alter code in uncontrolled loops, FeCode enforces an explicit engineering lifecycle:

$$\text{Prompt} \longrightarrow \text{Plan} \longrightarrow \text{Risk Assessment} \longrightarrow \text{Approval Gate} \longrightarrow \text{Execution Handoff} \longrightarrow \text{Verification}$$

FeCode runs 100% in your terminal through an interactive Ink/React interface. It inspects local projects, generates structured task plans, classifies risks, acquires explicit human consent for state modifications, and verifies that code compiles and tests pass before declaring a task complete.

Why FeCode

Traditional terminal coding assistants operate on a direct execution model:

Traditional Assistant:
User prompt ──▶ Model emits shell command / file edit ──▶ Blind execution ──▶ Unintended workspace corruption

FeCode treats code mutation as a protected operational boundary:

FeCode Safety Pipeline:
User prompt
     │
     ▼
Repository Inspection & Context Detection
     │
     ▼
Structured Task Plan (Inspectable, Step-by-Step)
     │
     ▼
Deterministic Risk Classification (NORMAL · ELEVATED · CRITICAL)
     │
     ▼
Interactive Human Approval Gate (Single-use, Non-transferable)
     │
     ▼
Rollback Checkpoint Creation (Git snapshot / File backup)
     │
     ▼
ExecutionHandoffManager (Authoritative Protected Boundary)
     │
     ▼
Verification Loop (Unit tests, typechecks, drift detection)
     │
     ▼
Deterministic Completion Summary

Core Tenets

Plan First: Every complex request is decomposed into an ordered, inspectable plan before execution begins.
Explicit Authorization: No file modification, file deletion, or terminal command executes without explicit approval.
Single-Use Consents: Permissions cannot be silently inherited or reused across steps, tasks, or resumed sessions.
No Destructive Retries: Destructive operations are never blindly re-executed on failure.
Durable History: Runs are persisted to disk with sanitized credentials, enabling post-mortem diagnostics and deterministic resumption.

Key Features

| Capability | Description | | :--- | :--- | | Inspectable Planning | Translates ambiguous developer requests into explicit, ordered plan steps. | | Deterministic Risk Engine | Classifies every action into NORMAL, ELEVATED, or CRITICAL risk tiers based on files and tools touched. | | Authoritative Handoff | All protected tool executions route exclusively through the ExecutionHandoffManager boundary. | | Single-Use Checkpoints | Captures pre-execution Git state snapshots to allow safe inspection and deterministic rollback. | | Verification Loops | Validates code modifications with compiler checks and test commands before claiming completion. | | Bounded Recovery | Detects execution failures and offers guided remediation without unbounded autonomous looping. | | Fresh-Auth Resume | Resumes interrupted or failed tasks under a new lineage with strictly re-prompted authorization. | | Git Drift Tracking | Compares baseline workspace state against modified files to detect external edits and prevent data loss. | | Interactive TUI | Built with Ink and React, providing a responsive terminal UI with progress bars, modals, and split views. | | Multi-Provider Support | First-class support for Google Gemini, OpenAI, and local Ollama models. |

Execution Safety Model

FeCode’s safety guarantees are formal system invariants verified by continuous automated test suites:

Authoritative Execution Boundary: Tools cannot bypass the ExecutionHandoffManager. There is no direct execution route from the LLM prompt to the host operating system.
Deterministic Risk Invariance: Action risk is calculated prior to execution and cannot be downgraded by prompt injection or model suggestion.
Approval Isolation: Approvals granted for step $N$ expire immediately upon completion and cannot satisfy step $N+1$.
Resumed Run Isolation: A resumed session receives a brand-new run ID. Approvals from the original run are void.
Bounded Retry Limit: Flaky or failing commands are limited by bounded retry policies; FeCode never enters an infinite loop.
Credential Sanitization: Persisted run history, telemetry dumps, and error logs automatically strip API keys and authorization tokens.

Installation

FeCode requires Node.js >= 20.0.0 and npm >= 10.0.0.

Global Package Installation (Recommended)

# Install globally via npm
npm install -g fecode-cli

# Verify installation
fe --version
fecode --version

Install From Source

# Clone the repository
git clone https://github.com/Abhijat05/FeCode.git
cd FeCode

# Install dependencies and compile all packages
npm install
npm run build

# Link CLI locally
npm link --workspace=apps/cli

For detailed platform instructions and environment requirements, see the Installation Guide.

Quick Start

1. Configure Provider Credentials

Set your provider and credentials using environment variables or a .env file in your workspace:

# Option 1: Google Gemini (Recommended Default)
export FE_PROVIDER="gemini"
export FE_MODEL="gemini-2.5-flash"
export GEMINI_API_KEY="your-gemini-api-key"

# Option 2: OpenAI
export FE_PROVIDER="openai"
export FE_MODEL="gpt-4o"
export OPENAI_API_KEY="your-openai-api-key"

# Option 3: Local Ollama (Completely Offline)
export FE_PROVIDER="ollama"
export FE_MODEL="qwen2.5-coder"
export OLLAMA_BASE_URL="http://localhost:11434/v1"

# Option 4: Generic OpenAI-Compatible / NVIDIA (e.g. DeepSeek on NVIDIA NIM)
export FE_PROVIDER="openai-compatible"
export FE_MODEL="deepseek-ai/deepseek-v4.1-flash"
export OPENAI_API_KEY="your-nvidia-api-key"
export OPENAI_BASE_URL="https://integrate.api.nvidia.com/v1"

2. Launch FeCode

Navigate to any project repository and run fe:

cd /path/to/your/project
fe

3. Issue Your First Task

> Inspect this project, explain its architecture, and run the test suite.

FeCode will:

Detect project framework and package structure (Node.js, TypeScript, Git).
Generate an explicit 3-step task plan.
Display the plan in the terminal and request approval for any command execution.
Execute inspected steps and stream formatted output.
Provide a verified completion summary with Git change attribution.

Read the complete Getting Started Guide for deeper workflow examples.

Configuration

FeCode supports layered configuration with deterministic precedence:

CLI Flags  ──▶  Environment Variables  ──▶  Workspace .env  ──▶  Built-in Defaults
(Highest)                                                               (Lowest)

Environment Variables

Refer to Configuration Documentation for full configuration specs.

Supported Providers

FeCode abstracts model providers behind a unified streaming interface in @fecode/models:

| Provider | Recommended Models | Streaming | Function Calling | Local / Offline | | :--- | :--- | :---: | :---: | :---: | | Google Gemini | gemini-2.5-flash, gemini-1.5-pro | Yes | Yes | Cloud | | OpenAI | gpt-4o, gpt-4o-mini | Yes | Yes | Cloud | | Generic OpenAI-Compatible | deepseek-ai/deepseek-v4.1-flash, NVIDIA NIM, vLLM, etc. | Yes | Yes | Cloud / Self-Hosted | | Ollama | qwen2.5-coder, deepseek-coder | Yes | Yes | Local (100% Offline) |

CLI & Slash Commands

Command Line Flags

fe [options]
fecode [options]

Options:
  -v, --version       Display FeCode version
  -h, --help          Display help and command overview
  -r, --resume <id>   Resume an interrupted session or historical run by ID

Interactive In-Terminal Slash Commands

Inside the active FeCode terminal session, type / to access built-in commands with autocomplete:

For complete usage documentation, see CLI Usage.

Keyboard Shortcuts

Git Awareness & Workspace Tracking

FeCode integrates with Git to protect against silent data loss:

Baseline Snapshots: Captures repository commit hash, branch, and untracked file state before task execution starts.
Drift Detection: Detects if files were modified externally while a plan was in progress.
Attribution & Diffing: Segregates changes made by FeCode from pre-existing uncommitted user changes.
No Automatic Commits: FeCode never executes git commit or git push automatically. You retain complete authority over your commit history.

Diagnostics & Durable History

Every execution creates a durable, sanitized run record on disk:

Telemetry: Records tool invocation latencies, token consumption, and model round-trips.
Sanitized Storage: Credentials, environment variables, and private auth headers are stripped prior to serialization.
Audit Trails: Inspect any run using /run <id> or view active performance via /diagnostics.

Learn more in the Diagnostics & Telemetry Guide.

Monorepo & Development

Repository Structure

fecode/
├── apps/
│   └── cli/            # Ink / React interactive terminal app (@fecode/cli)
├── packages/
│   ├── agent/          # Agent runtime, planning, checkpoints, recovery (@fecode/agent)
│   ├── models/         # Model providers (Gemini, OpenAI, Ollama) (@fecode/models)
│   └── shared/         # Common utilities, config loader, logger (@fecode/shared)
├── docs/v1/            # Comprehensive technical documentation
└── assets/             # Project visual assets

Development Commands

# Build all packages
npm run build

# Start interactive CLI in development mode (tsx)
npm run dev

# Run strict TypeScript compiler checks
npm run typecheck

# Run ESLint across entire codebase
npm run lint

# Run full Vitest automated test suite
npm test

Contributing

We welcome contributions from the community! Please read our Contributing Guide for setup instructions, coding conventions, and pull request workflows.

Security Policy

For vulnerability reporting guidelines and our security policy, please review SECURITY.md.

License

FeCode is open-source software licensed under the MIT License.
Copyright (c) 2026 Abhijat Sinha.