{"id":49232157,"url":"https://github.com/1024xengineer/neo-code","last_synced_at":"2026-05-11T10:01:50.966Z","repository":{"id":345421104,"uuid":"1183391347","full_name":"1024XEngineer/neo-code","owner":"1024XEngineer","description":"NeoCode 是一个本地优先的 AI Coding Agent，支持终端、Web、桌面端与飞书等多入口接入，帮助用户读懂项目、修改代码、运行命令并安全推进开发任务","archived":false,"fork":false,"pushed_at":"2026-05-08T15:40:26.000Z","size":9019,"stargazers_count":23,"open_issues_count":16,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-08T17:36:04.180Z","etag":null,"topics":["agent","claude-code","cli","golang","opencode","tui"],"latest_commit_sha":null,"homepage":"https://neocode-docs.pages.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/1024XEngineer.png","metadata":{"files":{"readme":"README.en.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-16T15:03:24.000Z","updated_at":"2026-05-08T15:38:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/1024XEngineer/neo-code","commit_stats":null,"previous_names":["1024xengineer/neo-code"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/1024XEngineer/neo-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1024XEngineer%2Fneo-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1024XEngineer%2Fneo-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1024XEngineer%2Fneo-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1024XEngineer%2Fneo-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/1024XEngineer","download_url":"https://codeload.github.com/1024XEngineer/neo-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1024XEngineer%2Fneo-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32889972,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"online","status_checked_at":"2026-05-11T02:00:05.975Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","claude-code","cli","golang","opencode","tui"],"created_at":"2026-04-24T12:15:11.043Z","updated_at":"2026-05-11T10:01:50.960Z","avatar_url":"https://github.com/1024XEngineer.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[中文](README.md) | [EN](README.en.md)\n\n# \u003cimg src=\"docs/assert/readme/neo-code.svg\" alt=\"neo-code\" /\u003e\n\n\u003e A local-first AI coding agent that helps you understand code, edit projects, call tools, and connect your development workflow across terminal, desktop, and automation.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://go.dev/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go\u0026logoColor=white\" alt=\"Go Version\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/1024XEngineer/neo-code\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/1024XEngineer/neo-code/branch/main/graph/badge.svg\" alt=\"Codecov Coverage\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/1024XEngineer/neo-code/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-purple?logo=opensourceinitiative\u0026logoColor=white\" alt=\"License MIT\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://neocode-docs.pages.dev/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Docs-Official-1677FF?logo=readthedocs\u0026logoColor=white\" alt=\"Docs\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://neocode-docs.pages.dev/en/guide/install\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-4EAA25\" alt=\"Platform\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://neocode-docs.pages.dev/en/\"\u003eDocs\u003c/a\u003e\n  ·\n  \u003ca href=\"https://github.com/1024XEngineer/neo-code/issues\"\u003eIssues\u003c/a\u003e\n  ·\n  \u003ca href=\"https://github.com/1024XEngineer/neo-code/discussions\"\u003eDiscussions\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What Is NeoCode?\n\nNeoCode is an AI coding agent that runs in your local development environment.\n\nIt can read your workspace, understand code, call tools, execute commands, manage sessions, and expose a unified local Gateway interface via JSON-RPC / SSE / WebSocket for terminal, desktop, or third-party clients.\n\nCore loop:\n\n`User Input (TUI) -\u003e Gateway Relay -\u003e Runtime Reasoning -\u003e Tool Calls -\u003e Result Feedback -\u003e UI Rendering`\n\n---\n\n## Features\n\n- Local-first: runs in your workspace with real project context.\n- Terminal interaction: conversational coding-agent experience based on TUI.\n- Tool calls: supports file access, project inspection, command execution, and system tools.\n- Multi-provider support: OpenAI, Gemini, ModelScope, Qiniu, OpenLL, and custom providers.\n- Session persistence: save and restore historical sessions to reduce repeated context switching.\n- Memory: store preferences, project facts, and cross-session context.\n- Skills system: enable specialized behaviors and workflows for different tasks.\n- MCP integration: extend external tool capabilities through MCP stdio servers.\n- Gateway mode: connect desktop apps, scripts, and third-party clients via local JSON-RPC / SSE / WebSocket.\n- Web UI: launch browser-based interface with `neocode web` for visual chat and session management.\n- Feishu Adapter: supports both Webhook and SDK long-connection access, with continuous run status updates in a single status card.\n- Local Runner: `neocode runner` executes tools locally and actively connects to a cloud Gateway via WebSocket, with no inbound port required.\n\n---\n\n## Preview\n\n![NeoCode TUI chat view](docs/assert/readme/preview-1.png)\n![NeoCode Web UI view](docs/assert/readme/preview-2.png)\n![NeoCode Feishu adapter view](docs/assert/readme/preview-3.png)\n\nMore screenshots and interaction details:\n- [Web UI Guide](https://neocode-docs.pages.dev/guide/web-ui)\n- [Feishu Remote Setup](https://neocode-docs.pages.dev/guide/feishu-remote-setup)\n\n---\n\n## Quick Start\n\n### 1. Install\n\nmacOS / Linux:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.sh | bash\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.ps1 | iex\n```\n\n### 2. Run from source\n\n```bash\ngit clone https://github.com/1024XEngineer/neo-code.git\ncd neo-code\ngo run ./cmd/neocode\n```\n\n### 3. Configure API key\n\nSet the environment variable for your selected provider, for example:\n\n```bash\nexport OPENAI_API_KEY=\"your_key_here\"\n```\n\nWindows PowerShell:\n\n```powershell\n$env:OPENAI_API_KEY = \"your_key_here\"\n```\n\nThen start in your project directory:\n\n```bash\nneocode -w /path/to/your/project\n```\n\nIf you want to use the browser-based Web UI, run:\n\n```bash\nneocode web\n```\n\nTagged release builds already embed Web UI assets (`web/dist`) into the `neocode` binary, so running `neocode web` does not require Node.js or npm on the target machine. If you run from source with `go run ./cmd/neocode web`, NeoCode will still automatically try to build the frontend when `web/dist` is missing.\n\nElectron desktop releases use the checked-in `web/build/icon.png`, `web/build/icon.ico`, and `web/build/icon.icns` assets. Only run `npm run generate:icons` from `web/` after replacing the source `web/build/icon.png`; the command uses PowerShell/.NET image APIs on Windows, `sips` on macOS, and requires ImageMagick's `magick` command on Linux.\n\n### 4. Quick Web / Feishu Entry\n\n```bash\n# Browser Web UI (default 127.0.0.1:8080)\nneocode web\n\n# Specify Web UI listen address (for local debugging)\nneocode web --http-listen 127.0.0.1:8080 --skip-build\n\n# Feishu SDK mode (recommended, no public ingress required)\nneocode feishu-adapter --ingress sdk --gateway-listen \"127.0.0.1:8080\"\n\n# Feishu Webhook mode (requires callback-reachable address from Feishu)\nneocode feishu-adapter --ingress webhook --gateway-listen \"127.0.0.1:8080\" --listen \"127.0.0.1:18080\"\n```\n\nDetailed guides:\n- [Web UI Guide](https://neocode-docs.pages.dev/guide/web-ui)\n- [Feishu Remote Setup (SDK / Webhook)](https://neocode-docs.pages.dev/guide/feishu-remote-setup)\n\n### 5. Common commands\n\n```text\n/help                 Show help\n/provider             Switch provider\n/model                Switch model\n/compact              Compact current session context\n/memo                 Show memory\n/remember \u003ctext\u003e      Save memory\n/skills               List available skills\n/skill use \u003cid\u003e       Enable a skill\n/skill off \u003cid\u003e       Disable a skill\n```\n\n### 6. CLI Routing Quick Reference\n\n#### Provider management\n\nUse these commands to add, list, and remove custom providers. Changes are stored under `~/.neocode/providers/`.\n\n```bash\n# Add a custom provider (ensure --api-key-env points to an existing environment variable)\nneocode provider add \u003cname\u003e --driver \u003cdriver\u003e --url \u003curl\u003e --api-key-env \u003cenv\u003e [--discovery-endpoint \u003cpath\u003e]\n\n# Example\nexport MOCK_KEY=\"sk-xxx\"\nneocode provider add my-openai --driver openaicompat --url https://api.openai.com/v1 --api-key-env MOCK_KEY --discovery-endpoint /v1/models\n\n# List all providers\nneocode provider ls\n\n# Remove a custom provider\nneocode provider rm my-openai\n```\n\n#### Model selection\n\nUse these commands to list model candidates for the current provider and switch to a specific model.\n\n```bash\n# List available models for the current provider (prefer local snapshot; trigger one sync discovery only when needed)\nneocode model ls\n\n# Set current model (validates model ownership against the current provider)\nneocode model set \u003cmodel-id\u003e\n\n# Example\nneocode model set gpt-4.1\n```\n\n#### One-step provider + model switch\n\nUse this flow to switch provider, and optionally override the auto-selected model via `--model`.\n\n```bash\n# Switch provider only (auto-corrects to an available model)\nneocode use \u003cprovider\u003e\n\n# Switch provider and set model (with provider-model ownership validation)\nneocode use \u003cprovider\u003e --model \u003cmodel-id\u003e\n\n# Example\nneocode use openai --model gpt-4.1\n```\n\n#### Local Runner\n\nStart a local execution daemon that actively connects to a cloud Gateway and receives tool-execution requests.\n\n```bash\n# Start runner (connects to 127.0.0.1:8080 by default)\nneocode runner\n\n# Set remote Gateway address and token\nneocode runner --gateway-address \"your-gateway.com:8080\" --token-file ~/.neocode/auth.json\n\n# Set runner name and working directory\nneocode runner --runner-name \"My Local Machine\" --workdir /path/to/project\n# Start feishu adapter (SDK mode, no public network required)\nneocode adapter feishu --ingress sdk --gateway-listen \"127.0.0.1:8080\"\n```\n\n### 7. Shell Diagnostic Agent\n\nUse these commands to enter proxy shell mode, initialize shell integration, trigger manual diagnosis, and manage automatic diagnosis.\n\n```bash\n# Enter proxy shell (currently Unix-like only)\nneocode shell\n\n# Print shell integration script (also supports --init \u003cshell\u003e)\nneocode shell --init bash\nneocode shell --init zsh\n\n# Trigger one manual diagnosis (both forms are equivalent)\nneocode diag\nneocode diag diagnose\n\n# Enter IDM interactive diagnostic sandbox (exit with \"exit\" or Ctrl+C when idle)\nneocode diag -i\n\n# Automatic diagnosis switch and status\nneocode diag auto on\nneocode diag auto off\nneocode diag auto status\n```\n\n### 8. URL Scheme Usage\n\nDetailed guide: [HTTP URL Wake-up Guide (User Story Version)](https://neocode-docs.pages.dev/guide/http-daemon-wake-user-guide)\n\n```bash\n# Start local HTTP daemon (default: 127.0.0.1:18921)\ngo run ./cmd/neocode daemon serve\n\n# Install user-level autostart + best-effort hosts alias write (127.0.0.1 neocode)\ngo run ./cmd/neocode daemon install\n\n# Check running and installation status\ngo run ./cmd/neocode daemon status\n\n# Uninstall autostart configuration\ngo run ./cmd/neocode daemon uninstall\n```\n\nClickable URL examples:\n\n```text\nhttp://neocode:18921/review?path=README.md\nhttp://neocode:18921/run?prompt=Write%20a%20simple%20HTTP%20server\n```\n\n\u003e Currently supported actions:\n\u003e - `review`: requires the `path` parameter.\n\u003e - `run`: requires the `prompt` parameter. Gateway returns `session_id` and triggers terminal handoff.\n\nSession handoff startup:\n\n```bash\ngo run ./cmd/neocode --session \u003csession_id\u003e\n```\n\n\u003e When `--session` is provided, TUI first attempts context handoff using the `workdir` saved in session history. If that path is no longer valid locally, NeoCode keeps the current workspace and displays a warning.\n\u003e\n\u003e On Linux (and other non-Windows/macOS platforms), automatic terminal popup is not yet integrated. `wake.run` returns `not_supported`, and you can manually run `neocode --session \u003csession_id\u003e` for handoff.\n\u003e\n\u003e `daemon serve` does not provide `--token-file`, listens only on `127.0.0.1`, and limits Host allowlist to `neocode` / `localhost` / `127.0.0.1`.\n\u003e\n\u003e Linux autostart strategy: prefer `systemd --user`; fall back to `~/.config/autostart/neocode-daemon.desktop` when unavailable.\n\u003e\n\u003e If NeoCode was not installed via install script (for example, built from source or using a bare binary), run `neocode daemon install` manually once.\n\n---\n\n## Documentation Map (By Scenario)\n\nOfficial docs site (English): [https://neocode-docs.pages.dev/en/](https://neocode-docs.pages.dev/en/)\n\nRecommended reading path:\n\n1. First-time setup\n- [Installation Guide](https://neocode-docs.pages.dev/guide/install)\n- [Daily Use Guide](https://neocode-docs.pages.dev/guide/daily-use)\n- [Configuration Guide](https://neocode-docs.pages.dev/guide/configuration)\n\n2. Entry surfaces (Web / Feishu)\n- [Web UI Guide](https://neocode-docs.pages.dev/guide/web-ui)\n- [Feishu Remote Setup (SDK / Webhook)](https://neocode-docs.pages.dev/guide/feishu-remote-setup)\n- [HTTP URL Wake-up Guide](https://neocode-docs.pages.dev/guide/http-daemon-wake-user-guide)\n\n3. Extensibility (MCP / Skills / Hooks)\n- [MCP Integration](https://neocode-docs.pages.dev/guide/mcp)\n- [Skills Guide](https://neocode-docs.pages.dev/guide/skills)\n- [Hooks Guide](https://neocode-docs.pages.dev/guide/hooks)\n- [Tools and Permissions](https://neocode-docs.pages.dev/guide/tools-permissions)\n\n4. Protocol and internals\n- [Gateway Integration \u0026 Protocol (Reference)](https://neocode-docs.pages.dev/reference/gateway)\n- [Runtime / Provider Event Flow (Repo Doc)](docs/runtime-provider-event-flow.md)\n\n5. Maintenance and troubleshooting\n- [Update Guide](https://neocode-docs.pages.dev/guide/update)\n- [Troubleshooting](https://neocode-docs.pages.dev/guide/troubleshooting)\n\nDocs site source is under `www/`. Local preview:\n\n```bash\ncd www\npnpm install\npnpm docs:dev\n```\n\n---\n\n## Contributing\n\nContributions via Issues, Discussions, and Pull Requests are welcome.\n\nSuggested workflow:\n\n1. Describe your problem, requirement, or design idea in an Issue first.\n2. Fork the repository and create a feature branch.\n3. Keep your changes focused and explain motivation and impact clearly.\n4. Run baseline checks before submitting:\n\n```bash\ngofmt -w ./cmd ./internal\ngo test ./...\ngo build ./...\n```\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1024xengineer%2Fneo-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F1024xengineer%2Fneo-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1024xengineer%2Fneo-code/lists"}