JoinCode

🌐 Languages: English | 简体中文

JoinCode is a pure C# open-source AI coding agent that runs in your terminal. It understands your codebase and helps you code faster through natural language — executing everyday tasks, explaining complex code, and handling Git workflows, all in a single command.

It compiles to a native single-file executable jcc.exe with zero runtime dependencies and peak performance on launch.

📖 Engineering rules: AGENTS.md (Chinese) · ADR

Why JoinCode?

🚀 Native performance — NativeAOT compiles to a single-file native binary. No JIT, no GC pauses, no runtime dependencies, millisecond cold start.
🧠 Multi-provider — DeepSeek / OpenAI / Anthropic / Azure / SenseNova / Agnes / Zhipu out of the box. Supports OpenAI Chat Completions, Anthropic Messages, and OpenAI Responses protocols.
🔧 Rich built-in tools — Shell execution, file operations, web requests, code indexing (TreeSitter AST), browser automation, skill system.
🔌 MCP protocol — Full Model Context Protocol client (version 2025-11-25 Streamable HTTP). Two-phase tool loading for infinite extensibility.
🛡️ Production-grade resilience — LLM fault tolerance (JSON repair, parameter normalization, tool-name canonicalization), three-tier loop intervention, prefix-cache optimization, tool-inertia error correction.
⚖️ Structured reasoning — /falv adversarial three-branch engine (Prosecution → Defense → Judge) with DAG evidence chains and dual budgets.
🎯 Multi-agent collaboration — /goal task-graph engine with hot-spot detection replacing file locks.
🖥️ Multi-mode UI — CLI interactive REPL + non-interactive script + TUI full-screen interface (Terminal.Gui v2).
📦 Zero Microsoft AI dependency — Rejects all AOT-incompatible Microsoft AI SDKs; builds LLM adapters from the protocol layer.

Quick Start

Prerequisites

.NET 10 SDK (10.0.301+)
Windows / Linux / macOS (NativeAOT cross-platform)

Build

git clone <repo-url>
cd JoinCode

# Build entire solution (Release enables NativeAOT)
dotnet build build/sln/JoinCode.slnx -c Release --no-incremental

# Or use the build script
.\build.ps1 -Mode Fast -SkipTests -Configuration Release

Output: artifacts/bin/JoinCode/Release/net10.0/jcc.exe

Configure Authentication

Set LLM provider via environment variables:

Variable	Required	Description	Example
`JCC_VENDOR`	No	Provider name (default: `deepseek`)	`deepseek` / `openai` / `anthropic` / `azure` / `sensenova` / `agnes`
`JCC_MODEL_ID`	No	Model ID (default: `deepseek-v4-flash`)	`gpt-4o` / `claude-opus-5-20250815`
`JCC_ENDPOINT`	No	API endpoint (default: provider built-in)	`http://localhost:9901`

Provider API keys:

Provider	Environment Variable	Default Endpoint
`deepseek`	`DEEPSEEK_API_KEY`	Built-in (OpenAI-compatible)
`openai`	`OPENAI_API_KEY`	`https://api.openai.com/v1`
`anthropic`	`ANTHROPIC_API_KEY`	`https://api.anthropic.com` (or SenseNova relay)
`azure`	`AZURE_OPENAI_API_KEY`	User-configured Azure OpenAI
`sensenova`	`SENSENOVA_API_KEY`	`https://token.sensenova.cn/v1`
`agnes`	`AGNES_API_KEY`	`https://apihub.agnes-ai.com/v1`

Run

# Non-interactive (single prompt, for scripting)
jcc --trust -p "Explain this codebase architecture"

# Interactive REPL
jcc --trust

# TUI full-screen mode (standalone jcctui.exe, Terminal.Gui v2)
jcctui --trust

# Specify model
jcc --trust -m gpt-4o

# Bypass all permission checks (equivalent to --permission-mode bypass)
jcc --bypass -p "batch refactor"

# Diagnostic mode
jcc --debuglog -p "hello"

CLI Reference

Basic:

Flag	Description
`--help` / `-h`	Show help
`--version` / `-v`	Show version
`--prompt <text>` / `-p`	Non-interactive single prompt
`--model <id>` / `-m`	Model ID or alias
`--vendor <name>`	Switch LLM provider (auto-match settings.json vendor preset)
`--pipe <name>`	Named pipe communication
`jcctui`	Launch standalone TUI full-screen interface (Terminal.Gui v2)

Output:

Flag	Description
`--non-interactive`	Force non-interactive mode (read from stdin, write to stdout)
`--json`	Structured JSON output (subcommands and non-interactive mode)
`--format <text\|json\|ndjson>`	Output format (default: text)
`--quiet` / `-q`	Quiet mode (errors only)

Permission:

Flag	Description
`--trust`	Trust current directory (skip trust prompt)
`--permission-mode <mode>`	Permission mode: `plan` / `auto` / `ask` / `bypass`
`--bypass`	Skip all permission checks (equivalent to `--permission-mode bypass`)
`--no-confirm`	Skip all confirmation prompts
`--yes` / `-y`	Skip all confirmation prompts (equivalent to `--no-confirm`)
`--force` / `-f`	Force execution (skip permission checks and confirmations)
`--allowed-tools <list>`	Tool whitelist (comma-separated, e.g. `Read,Edit,Bash(git:*)`)
`--disallowed-tools <list>`	Tool blacklist (comma-separated)
`--dry-run`	Dry-run mode (show operations without executing)

Session:

Flag	Description
`--continue` / `-c`	Continue the most recent session
`--resume <id>` / `-r`	Resume a specific session (by session-id or title keyword)

Prompt:

Flag	Description
`--system-prompt <text>`	Replace system prompt (overrides default)
`--append-system-prompt <text>`	Append to system prompt (does not override)

Diagnostics:

Flag	Description
`--debuglog` / `-d`	Enable debug logging (equivalent to `JCC_DEBUGLOG=1`)
`--await <seconds>`	Non-interactive timeout auto-close (returns 1234 on timeout)
`--force-interactive`	Force interactive mode even if stdin is redirected (for E2E tests)

Slash Commands

Session & Chat:

Command	Description
`/help`	List all commands
`/clear`	Clear chat history (aliases: `reset`, `new`, `cls`)
`/compact`	Compact context toGPT to save tokens (alias: `comp`)
`/rewind`	Restore code/conversation to previous state (alias: `checkpoint`)
`/fork`	Create a conversation branch (alias: `branch`)
`/resume`	Resume a previous session (alias: `continue`)
`/exit`	Exit (alias: `x`)

Models & Providers:

Command	Description
`/model <name>`	Switch model (e.g., `/model flash`, `/model pro`)
`/vendor <name>`	Switch LLM provider (`openai` / `anthropic` / `deepseek` / …)
`/sampling`	Set temperature / max tokens
`/effort`	Adjust reasoning effort (`low` / `medium` / `high` / `max` / `auto`)

Agents & Reasoning:

Command	Description
`/goal`	Goal autonomous loop engine (Outcome + Verification + Constraints)
`/falv`	Structured reasoning (three-branch + evidence chain + dual budget)
`/plan`	Plan mode management
`/agents`	View and manage agents
`/tasks`	List and manage background tasks

Tools & Config:

Command	Description
`/mcp`	Manage MCP servers
`/config`	Manage configuration settings
`/permissions`	Manage permission rules
`/tools`	List available tools
`/init`	AI-driven project config initialization
`/doctor`	Diagnose environment (alias: `dr`)

Info:

Command	Description
`/status`	Show version, model, account, API status
`/cost`	Show usage cost statistics
`/stats`	Show session statistics
`/context`	Show context statistics

Run /help in JoinCode for the complete list of 80+ commands.

Core Features

Code Understanding & Generation

Query and edit large codebases — 3,313 files AST-parsed in ~2.7s
TreeSitter-driven code indexing with incremental AST (no persistence needed)
Debug and troubleshoot with natural language

Automation & Integration

Automate ops tasks — query PRs, handle complex rebases, batch refactor
Connect MCP servers for custom tools, skills, and workflows
Integrate jcc -p "..." into CI/CD scripts

Production-Grade Resilience

LLM fault tolerance: JSON format repair, parameter name normalization, type auto-conversion, tool-name canonicalization
Three-tier loop intervention: Soft prompt → hard truncation + cooldown retry → context compaction + unattended recovery
Prefix-cache optimization: System prompt partitioning + message history prefix preservation + DeepSeek cache statistics
Smart progress discount: Lower intervention level when real progress is detected

Structured Reasoning (`/falv`)

Three-branch adversarial: Prosecution (collect evidence) → Defense (rebut) → Judge (rule)
DAG evidence chain + dual budget control (rounds + tokens, whichever runs out first stops)
Three proof standards: Murder (beyond reasonable doubt) / Panda (circumstantial) / Divorce (preponderance of evidence)
/falv --continue to extend reasoning

Multi-Agent Collaboration (`/goal`)

Task-graph engine based on PRD v2.1, reusing team MCP shared components
Hot-spot detection replaces file locks: HotFileDetector + IntentCollector + HotSpotTracker + HotSpotResolutionPolicy
Contract change broadcast: ContractChangeBroadcaster + ContractChangeNotificationRouter
Captain dispatch + merge queue: CaptainDispatchGuard + MergeQueueService + DeferredMailService
22 new components + 4 integration tasks + 7 breakpoint fixes, 3300+ tests zero breakage

Native Performance

NativeAOT single-file native binary, zero runtime dependencies
Source generators eliminate runtime reflection
Seven-layer slnx isolation, strict dependency-ordered builds, zero circular dependencies
14 middleware pipelines (Chat/Permission/Shell/Web/Skill…), onion model with explicit manual registration

Architecture

✅ Architecture migration complete — ADR 0103 restructured from numeric prefixes (00_generators/~09_app_*) to semantic grouping (build/ gen/ lib/ llm/ kit/ server/ app/ test/ tool/) with flat internals (eliminating src/+tests/ double layer). See [docs/proposed/design/DSG004-flatten-restructure-plan.md). Paths below reflect the new semantic structure.

JoinCode uses a seven-layer solution isolation architecture with strict dependency ordering:

① Generators      →  gen/*/ (source generators, netstandard2.0)
② Foundation      →  lib/*/ (abstractions, async lock, plugins, transport contracts)
③ Infrastructure  →  lib/*/ (infrastructure, transport impl)
④ Core            →  kit/*/ (ai, execution, safety, search)
⑤ Services        →  server/*/ + llm/*/ (MCP, vision, bridge, dream, eyes, …)
⑥ Composition     →  kit/*/ (composition, clock, pipelines)
⑦ App             →  app/*/ (JoinCode CLI, TUI, GUI, Sdk) + test/

Key Design Decisions

Decision	ADR
Seven-layer slnx isolation	0001
NativeAOT, no Microsoft AI packages	0002
Rebase over merge	0003
Config over code for modalities	0004
File-driven UI	0005
TDD double-layer	0006
Progressive development	0007
Archive to `.xxx/`, never delete	0008
Defense-in-depth L1–L10	0036

See docs/README.md for the full ADR index.

Source Generators

Generator	Purpose
`AotSafety.Generator`	AOT safety analysis + code org rules (JCC5002, JCC9006)
`EnumMetadata.Generator`	`[EnumValue]` → `XxxEnumConstants` + `XxxExtensions`
`McpToolDispatch.Generator`	MCP tool handler registration + `[Register]` DI
`PromptSection.Generator`	Prompt section generation
`PromptTemplate.Generator`	Prompt template generation
`ToolPrompt.Generator`	Tool prompt generation
`CliOption.Generator`	CLI option binding
`AppModule.Generator`	App module registration
`CodeFixes`	JCC code fixes

Middleware Pipelines

Pipeline	Subsystem	Middleware Chain
Chat	Brain	Timing→ErrorHandling→AuditLog→TokenBudget→PreChat→QueryLoop→LoopIntervention→ProcessUsage→CleanupInjections→SaveContext
Permission	Guard	Bypass→AgentRestriction→AutoClassifier→ConfigGetOperation→WebFetchPermission→EarlyPathDeny→ToolListPermission→PathPermission→DangerousOperation→PlanMode→AutoSafety→DefaultResult
Shell	Hands	Validation→Classification→SedIntercept→Background→BuildIntercept→Execution→Output
Web	Hands	Metrics→Validation→SsrfGuard→CacheCheck→DomainCheck→Fetch→ContentProcessing→CacheWrite
Skill	Hands	Metrics→Validation→Telemetry→Execution
Code	Hands	Cache→Security→Llm→Sandbox→Metrics
AgentSpawn	Agents	DefinitionResolution→PromptBuilding→ContextSetup→AgentWorktreeSpawn→HookSetup→McpSetup→Metadata→Transcript
Fork	Agents	ForkValidation→ForkSpawn→ForkPermission→ForkExecution
Settings	Guard	SettingsReload→EffortLevel→HookRefresh→PermissionCache
Preprocess	Brain	KeywordInjection→SynonymInjection→SystemPrompt→ReminderInjection→ToolListingInjection→LspDiagnostic
Compact	Brain	CompactHook→ContextCollapse→Microcompact→SessionMemoryCompact→ReactiveCompact
Query	Brain	UsdBudget→QueryTokenBudget→CostTracking→DiminishingReturns→HistorySnip→IdleReminder→StopHook→StateTransition→ContentReplacement
ChatInit	Brain	ContextLoad→CostRestore→ConfigChangeStart→SessionStartHook
ChatAdmin	Brain	SessionAdmin→SessionSave

Test Architecture

Test projects across 7 solution layers + cross-layer test center:

Layer	Location
① Generators	`generators/*/tests/`
② Foundation	`foundation/*/tests/Unit/`
③ Infrastructure	`tests/Unit/Infra.Tests/*/`
④ Core	`core/*/tests/`
⑤ Services	`services/*/tests/Unit/`
⑥ Composition	`composition/*/tests/Unit/`
⑦ App	`tests/Unit/Host.Tests/`, `tools/*/tests/`
Cross-layer	`tests/Unit/*.Tests/`, `tests/Integration/`, `tests/MockServers/`

CI Pipeline

CI is split into reusable workflows under .github/workflows/ (PR → main):

Workflow	Description
`ci.yml`	Main entry — calls sub-workflows
`ci-build.yml`	7-layer ordered build + component tests + satellite projects
`ci-unit-tests.yml`	Each csproj = 1 independent matrix job, `--filter "Category!=Integration&Category!=Benchmark"`
`ci-integration.yml`	`Integration.Tests` + App.slnx filter groups
`ci-e2e.yml`	MockServer.E2E.Tests + Sync.Integration.Tests + CodeIndex.E2E.Tests + smoke tests
`mutation-testing.yml`	Stryker.NET, scheduled daily

Configuration

Provider Configuration

Provider settings are stored in ~/.jcc/settings.json. The file ships with 51 model entries across 6 providers (50 unique models after cross-provider deduplication).

Switch models interactively with /model <alias>:

/model flash      # DeepSeek deepseek-v4-flash
/model pro        # DeepSeek deepseek-v4-pro
/model 4o         # OpenAI gpt-4o
/model opus5      # Anthropic claude-opus-5-20250815
/model 5.6        # OpenAI gpt-5.6-sol

Project-Level Configuration

Create .env/api.json in the project root for team-shared defaults:

{
  "env": {
    "DEEPSEEK_API_KEY": "sk-your-key",
    "JCC_VENDOR": "deepseek",
    "JCC_MODEL_ID": "deepseek-v4-flash"
  }
}

API Key Priority

From low to high:

~/.jcc/auth.json "deepseek" field
DEEPSEEK_API_KEY environment variable (highest priority)
Fallback: OPENAI_API_KEY environment variable

Detailed Documentation

Document	Description
Available Models	51 models across 6 providers (aliases, context length, notes)
Technical Details	Fault tolerance / prefix caching / loop intervention / parallel load / serial build
Small Model Strategy	Engineering strategies for small model scenarios (synonyms / prohibitions / counterexamples / match)
Architecture Index	Component dependency graph / detail table / internal structure / middleware pipelines / build commands
Architecture Decision Records	ADRs: why choice A over B

Contributing

We welcome contributions! Please read CONTRIBUTING.md for development setup, coding conventions, and the PR workflow.

Key points:

Follow the seven-layer build order
Use Conventional Commits format
TreatWarningsAsErrors is enabled — zero warnings allowed
Write ADRs for architecturally significant decisions
See AGENTS.md for detailed engineering rules (Chinese)

Testing

# All tests except integration
dotnet test App.slnx -c Release /p:SkipLocalPack=true --filter "Category!=Integration"

# Single component
dotnet test tests/Unit/Hands.Tests/Hands.Tests.csproj -c Debug --filter "Category!=Integration"

License

This project is licensed under the MIT License.

Acknowledgements

ByteDance TraeCN and Huawei Cloud CodeArts — for foundational tooling and inspiration
The open-source community for TreeSitter, Terminal.Gui, and all dependencies listed in our NuGet references

Contact

Email: superhong@foxmail.com
Issues: GitHub Issues
Security: See SECURITY.md — do not use public issues for security reports

Name		Name	Last commit message	Last commit date
.github		.github
build		build
docs		docs
libs		libs
modules		modules
non_deliverables_tools		non_deliverables_tools
test		test
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
Directory.Build.props		Directory.Build.props
Directory.Build.targets		Directory.Build.targets
LICENSE		LICENSE
README.md		README.md
global.json		global.json
nuget.config		nuget.config

Latest commit

History

Folders and files

Repository files navigation

JoinCode

Table of Contents

Why JoinCode?

Quick Start

Prerequisites

Build

Configure Authentication

Run

CLI Reference

Slash Commands

Core Features

Code Understanding & Generation

Automation & Integration

Production-Grade Resilience

Structured Reasoning (/falv)

Multi-Agent Collaboration (/goal)

Native Performance

Architecture

Key Design Decisions

Source Generators

Middleware Pipelines

Test Architecture

CI Pipeline

Configuration

Provider Configuration

Project-Level Configuration

API Key Priority

Detailed Documentation

Contributing

Testing

License

Acknowledgements

Contact

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Structured Reasoning (`/falv`)

Multi-Agent Collaboration (`/goal`)