jCodex: Enhanced Coding Agent Harness

Welcome to jCodex, an enhanced fork of the original jCode project. jCodex builds upon the exceptional foundation of jCode while addressing technical debt, implementing planned features, and delivering a more robust, maintainable, and feature-rich coding agent harness.

What is jCodex?

jCodex is a sophisticated Rust-based coding agent harness designed for developers who demand performance, flexibility, and power. It combines:

• Lightning-fast TUI: 14ms boot time, 48.7ms to first input
• Multi-model Support: Seamlessly switch between Claude, OpenAI, Gemini, and more
• Swarm Coordination: Multi-agent collaboration within the same repository
• Semantic Memory: Vector-based memory with automatic recall and consolidation
• Browser Automation: Built-in browser tool for web interaction
• 30+ Integrated Tools: From code analysis to system commands

Key Improvements Over jCode

Code Quality

• Dead Code Removal: Systematic removal of unused functions and modules
• File Decomposition: Breaking down large files (>1200 LOC) into focused, maintainable modules
• Error Handling: Comprehensive error types with contextual information
• Reduced Warnings: Strict compiler warnings with narrow, justified suppressions

New Features

• Custom Session Names: Name sessions explicitly or auto-generate from project directory
• Automatic Model Routing: Intelligent routing between thinking and routine models
• XDG Base Directory Support: Proper Linux filesystem hierarchy compliance
• Skill Manager: Dynamic skill loading, versioning, and context-aware activation
• Programmatic Orchestration API: Stable API for external harness integration

Bug Fixes

• Fixed /compact command that was destroying sessions
• Resolved Ollama model switching issues
• Corrected Minimax endpoint configuration
• Fixed ambient cycle type coercion bug
• Resolved Minimax thinking block display issues

Performance Enhancements

• Optimized build times (target: 5-20 seconds for incremental builds)
• Improved memory efficiency
• Enhanced TUI rendering performance

Quick Start

Installation

# Clone the repository
git clone https://github.com/crishacks/jcodex.git
cd jcodex

# Build from source
cargo build --release

# Install
./scripts/install_release.sh

# Verify installation
jcodex --version

First Run

# Launch the interactive TUI
jcodex

# Run a single command
jcodex run "analyze this code"

# Resume a previous session
jcodex --resume my-session

# Run as a background server
jcodex serve
jcodex connect

Core Components

Agent Runtime

The agent runtime orchestrates multi-turn conversations, tool execution, and state management. It handles:

• Request/response streaming
• Tool invocation and result processing
• Context window management
• Session persistence

Memory System

The semantic memory system enables agents to automatically recall relevant information:

• Vector embeddings for semantic search
• Memory extraction and consolidation
• Ambient mode for background processing
• Explicit memory tools for manual management

Provider Abstraction

Unified interface for multiple LLM providers:

• OpenAI (GPT-4, GPT-4 Turbo)
• Anthropic (Claude 3 family)
• Google (Gemini)
• Open Router
• Local providers (Ollama, Fireworks)
• And more

Tool System

Comprehensive tool suite for agent interaction:

• File operations (read, write, apply patches)
• Code analysis (grep, language analysis)
• System commands (bash, environment access)
• Browser automation (Firefox via Agent Bridge)
• Web search and information retrieval
• And 25+ more tools

Configuration

Basic Configuration

Create ~/.config/jcodex/config.toml:

[provider]
default = "openai"

[session]
auto_save = true
memory_enabled = true

[ui]
theme = "dark"
alignment = "left"  # or "center"

[performance]
embeddings_enabled = true
memory_consolidation_interval = 3600

Environment Variables

# Provider API keys
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."

# XDG directories
export XDG_CONFIG_HOME="$HOME/.config"
export XDG_DATA_HOME="$HOME/.local/share"
export XDG_CACHE_HOME="$HOME/.cache"

# Performance
export JCODEX_LOG_LEVEL="debug"
export JCODEX_ENABLE_PROFILING="true"

Development

Building

# Development build
cargo build

# Release build with optimizations
cargo build --release

# With all features
cargo build --release --all-features

# With embeddings (slower to compile)
cargo build --release --features embeddings

Testing

# Run all tests
cargo test --all

# Run specific test
cargo test --lib session::tests

# Run with output
cargo test -- --nocapture

# Run integration tests
cargo test --test '*'

# Run benchmarks
cargo bench --features "dev-bins"

Code Quality

# Format code
cargo fmt

# Check formatting
cargo fmt -- --check

# Run clippy (linter)
cargo clippy --all-targets --all-features -- -D warnings

# Check documentation
cargo doc --no-deps --open

# Check for security issues
cargo audit

Documentation

Comprehensive documentation is available in the docs/ directory:

• JCODEX_IMPROVEMENTS.md: Overview of all improvements
• IMPLEMENTATION_GUIDE.md: Detailed implementation instructions
• MEMORY_ARCHITECTURE.md: Semantic memory system design
• SWARM_ARCHITECTURE.md: Multi-agent coordination
• SERVER_ARCHITECTURE.md: Server/client architecture
• AMBIENT_MODE.md: Background processing and automation
• SAFETY_SYSTEM.md: Safety and security considerations
• REFACTORING.md: Code refactoring guidelines

Performance Metrics

jCodex demonstrates exceptional performance characteristics:

Metric	Value	vs Competitors
RAM (1 session)	27.8 MB	13.9× better than Claude Code
Boot Time	14.0 ms	245.5× faster than Claude Code
Time to First Input	48.7 ms	72.2× faster than Claude Code
RAM per Additional Session	~9.9 MB	21.5× better than Claude Code

Contributing

We welcome contributions! Please follow these guidelines:

1. Code Style: Follow Rust conventions and use cargo fmt
2. Testing: Add tests for new features and bug fixes
3. Documentation: Update docs for significant changes
4. Commits: Make focused, well-described commits
5. PRs: Reference issues and provide clear descriptions

See CONTRIBUTING.md for detailed guidelines.

Troubleshooting

Build Issues

# Clean build
cargo clean
cargo build --release

# Check dependencies
cargo tree

# Update dependencies
cargo update

Runtime Issues

# Enable debug logging
JCODEX_LOG_LEVEL=debug jcodex

# Check logs
tail -f ~/.jcodex/logs/jcodex-*.log

# Verify configuration
jcodex config --show

# Test provider connection
jcodex auth-test --all-configured

Support

• Issues: Report bugs on GitHub Issues
• Discussions: Join community discussions on GitHub Discussions
• Documentation: Check docs/ for detailed information
• Examples: See examples/ for usage patterns

License

jCodex is licensed under the same license as the original jCode project. See LICENSE for details.

Acknowledgments

jCodex builds upon the excellent work of the original jCode project by @1jehuang. We extend our gratitude for the foundation and inspiration.

Citation

If you use jCodex in your research or projects, please cite:

@software{jcodex2026,
  title={jCodex: Enhanced Coding Agent Harness},
  author={Cris Hacks},
  year={2026},
  url={https://github.com/crishacks/jcodex}
}

Changelog

See CHANGELOG.md for a detailed history of changes.

---