{"id":49264435,"url":"https://github.com/n1ghthill/devsynapse-ai","last_synced_at":"2026-05-03T02:10:19.818Z","repository":{"id":353505587,"uuid":"1219683722","full_name":"N1ghthill/devsynapse-ai","owner":"N1ghthill","description":"Open source development assistant with project-aware chat, constrained command execution, and usage telemetry.","archived":false,"fork":false,"pushed_at":"2026-05-02T18:59:40.000Z","size":8178,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T19:19:20.966Z","etag":null,"topics":["developer-tools","fastapi","llm","open-source","react","sqlite","vite"],"latest_commit_sha":null,"homepage":"https://github.com/N1ghthill/devsynapse-ai/tree/main/docs","language":"Python","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/N1ghthill.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-04-24T05:52:24.000Z","updated_at":"2026-05-02T18:59:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/N1ghthill/devsynapse-ai","commit_stats":null,"previous_names":["n1ghthill/devsynapse-ai"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/N1ghthill/devsynapse-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/N1ghthill%2Fdevsynapse-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/N1ghthill%2Fdevsynapse-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/N1ghthill%2Fdevsynapse-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/N1ghthill%2Fdevsynapse-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/N1ghthill","download_url":"https://codeload.github.com/N1ghthill/devsynapse-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/N1ghthill%2Fdevsynapse-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32555839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T00:31:16.350Z","status":"online","status_checked_at":"2026-05-03T02:00:09.297Z","response_time":103,"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":["developer-tools","fastapi","llm","open-source","react","sqlite","vite"],"created_at":"2026-04-25T09:10:02.813Z","updated_at":"2026-05-03T02:10:19.812Z","avatar_url":"https://github.com/N1ghthill.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DevSynapse AI\n\n[![CI](https://github.com/N1ghthill/devsynapse-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/N1ghthill/devsynapse-ai/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![Version](https://img.shields.io/badge/version-0.7.0-blue)\n\n**A local-first DeepSeek coding agent with safe command execution, project memory, and cost visibility.**\n\nRun an AI development assistant on your machine, connected to your own DeepSeek API key,\nwith project-aware context, controlled tools, audit logs and usage telemetry.\n\n![DevSynapse AI demo flow](docs/screenshots/devsynapse-demo-flow.gif)\n\nDevSynapse AI is built for Linux developers who want DeepSeek without losing local control:\nselect a project, ask for help, review the proposed command, confirm execution and see\nthe token/cost impact in the dashboard.\n\n## Why It Exists\n\nDeepSeek is strong for development work, but it does not ship with a dedicated\ncoding-agent environment. DevSynapse AI is that missing layer: a local-first\nbrowser workspace around your DeepSeek API key, with persistent memory,\ncontrolled command execution, project-scoped authorization and cost visibility.\n\nThe MVP focus is intentionally narrow: an AI coding assistant for Linux developers\nwho want DeepSeek without SaaS lock-in, hidden shell access or surprise API bills.\n\n## Core Loop\n\n1. Select the project you want DevSynapse to understand.\n2. Ask a development task such as `analyze this repo and run tests`.\n3. Review the proposed command, risk level, working directory and expected effect.\n4. Confirm the command only when the scope and risk are clear.\n5. Let DevSynapse interpret the result and preserve the conversation context.\n6. Track token usage, estimated cost, alerts and project attribution in the dashboard.\n\n## Use Cases\n\n- **Budget-conscious developer:** use DeepSeek through your own API key, keep conversations local, track token/cost usage and set daily or monthly budget thresholds.\n- **Freelancer with multiple clients:** keep project context explicit, scope mutating commands per project and report usage/cost by project.\n- **Contributor or maintainer:** inspect chat history, command outcomes, monitoring data, budget alerts, permissions and audit records from one local UI.\n\n## Try It On Linux\n\n```bash\nbash scripts/install.sh\n```\n\nThe supported installer target is Debian/Ubuntu-style Linux. The setup asks for\nyour DeepSeek API key and repositories directory, then registers local launcher\nand updater commands.\n\n## Desktop App Builds\n\nThe repository also contains a Tauri v2 desktop app under `frontend/src-tauri`.\nFor a local desktop build:\n\n```bash\nmake desktop-build\n```\n\nThat target compiles the Python sidecar, places it at\n`frontend/src-tauri/binaries/devsynapse-backend-{target-triple}`. Generate\nrelease builds on each target OS; PyInstaller does not cross-compile the Python\nbackend.\n\nCurrent desktop distribution status:\n\n| Platform | Status |\n| --- | --- |\n| Linux `.deb` | validated locally on 2026-04-27 |\n| Linux `.rpm` | validated locally on 2026-04-27 |\n| Linux AppImage | opt-in/experimental |\n| macOS | configured, not yet validated |\n| Windows NSIS installer | validated in GitHub Actions on 2026-04-27 |\n\nSee [TAURI.md](TAURI.md) for the build workflow and\n[docs/deployment/desktop-distribution.md](docs/deployment/desktop-distribution.md)\nfor landing-page artifact status.\n\n## Product Showcase\n\n| Controlled coding workflow | Cost and project telemetry |\n| --- | --- |\n| ![Chat command execution workflow](docs/screenshots/2026-04-24-chat-command-execution.png) | ![Dashboard with LLM usage and project cost reporting](docs/screenshots/2026-04-24-dashboard-llm-usage.png) |\n\n| DeepSeek and budget settings | Project permission administration |\n| --- | --- |\n| ![DeepSeek settings, budget controls and project access](docs/screenshots/2026-04-24-settings-project-access.png) | ![Admin project permissions and audit history](docs/screenshots/2026-04-24-admin-project-permissions.png) |\n\nMore context is available in the [product showcase](docs/product/showcase.md) and the [screenshot evidence index](docs/screenshots/README.md).\n\nTo generate fresh disposable evidence locally:\n\n```bash\nmake eval-agent\n```\n\nThe target writes Markdown and JSON reports under `/tmp/devsynapse-agent-evaluations/`\nand does not touch real user repositories. CI runs the no-LLM variant so the\ndisposable harness and command-policy checks stay continuously validated without\nrequiring secrets.\n\n## Evaluation Evidence\n\nRecent product evidence is organized under [docs/evaluation](docs/evaluation/README.md).\n\n- Real DeepSeek agent run on `2026-05-02`: DevSynapse inspected a disposable\n  Python project, diagnosed failing tests, edited the bug and finished with\n  `3 passed in 0.01s`.\n- Local orchestrator appraisal on `2026-05-02`: project scoping, command\n  authorization, blocked unsafe paths, telemetry and UI screenshots were\n  validated against disposable projects.\n\nThe real-LLM evidence includes screenshots, structured JSON output, token/cost\ntelemetry and the exact code diff produced by the agent:\n[real DeepSeek evidence](docs/evaluation/real-llm/2026-05-02-real-deepseek-evidence.md).\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE).\n\n## Verified Baseline\n\nLocal verification refreshed on `2026-05-03` (v0.7.0 repository baseline):\n- full repository verification: `make verify`\n- dependency consistency: `pip check`\n- frontend dependency audit: `npm audit --audit-level=high`\n- backend test suite: `229 passed`\n- Python/Ruff checks, shell syntax checks, Python script compilation and frontend ESLint: passed\n- frontend production build: passed\n- OpenAPI schema generation: passed\n- previous release validation also covered `make desktop-build`, `make ui-smoke` and GitHub Actions CI on `main`\n- supported shell installer target: Debian/Ubuntu-style Linux with `apt`\n- validated desktop artifacts: Linux `.deb` / `.rpm` and Windows NSIS installer; macOS is configured but not validated\n- LLM usage telemetry, streaming chat delivery, project selector, project manager, conversation persistence, execution workflow and dashboard metrics are active in the current codebase\n\n## What The Project Does\n\nDevSynapse AI provides:\n- a FastAPI backend for auth, chat, streaming chat (SSE), command execution, monitoring, settings and admin flows;\n- a React/Vite frontend with chat, project selector, dashboard, settings and admin interfaces;\n- SQLite-backed persistence for runtime state and migration-controlled schema evolution;\n- a DeepSeek API orchestration layer with native tool calling (strict function definitions, thinking mode), Flash/Pro routing, local agent learning, streaming token delivery, and execution result interpretation;\n- procedural memory with confidence/decay scoring, learning nudges after complex turns or command outcomes, and Markdown-backed reusable skills;\n- a constrained execution bridge for `bash`, `read`, `glob`, `grep`, `edit` and `write` with per-project working directories;\n- workflow templates for common local coding tasks such as test runs, failing-test analysis, TODO search, repository summaries, changelog drafts and Docker inspection;\n- visible project attribution in conversation summaries, chat messages, command execution and usage reporting;\n- per-user, project-scoped mutation authorization for non-admin users;\n- token, cache hit-rate and cost telemetry for LLM usage;\n- configurable daily/monthly LLM budgets with warning and critical thresholds, enabled by default.\n\n## Repository Map\n\n```text\ndevsynapse-ai/\n├── api/                    # FastAPI application, contracts and routes\n├── config/                 # Centralized settings and policy constants\n├── core/                   # Brain, auth, memory, monitoring, bridge, plugins\n├── docs/                   # Contributor-facing technical documentation\n├── frontend/               # React/Vite operator UI\n├── plugins/                # Plugin implementations\n├── scripts/                # Local operational utilities\n├── tests/                  # Unit and integration tests\n├── .env.example            # Runtime configuration template\n├── Makefile                # Common dev commands\n└── README_PROFESSIONAL.md  # Engineering-oriented companion doc\n```\n\n## Platform Support\n\nThe supported shell installer target is Linux, specifically Debian/Ubuntu and\nclose derivatives that use `apt`. The installer, updater and launcher are\nshell-based and assume `bash`, `python3`, `python3-venv`, `npm` and standard\nLinux paths.\n\nThe desktop packaging flow currently has validated Linux `.deb` / `.rpm`\nartifacts and a validated Windows x86_64 installer generated on GitHub Actions.\nmacOS desktop packaging is configured through Tauri, but release artifacts still\nneed to be generated and validated on macOS before they should be linked\npublicly.\n\nWindows users should use the packaged desktop installer for the validated\nWindows path. Native Windows source-checkout setup is still not a supported\nshell workflow: there is no PowerShell or `.bat` installer, and command-line\naliases/path behavior remain Linux-oriented.\n\nFor specific areas where community help is most needed, see the\n[Platform Contributions](CONTRIBUTING.md#platform-contributions) section in\n`CONTRIBUTING.md`.\n\n## Quick Start\n\n```bash\nbash scripts/install.sh\n```\n\nThe installer asks for your DeepSeek API key and repositories directory, then sets up\neverything automatically. Two shell aliases are registered:\n\n```bash\ndevsynapse              # start the app\nupdate-devsynapse       # update an existing install\nuninstall-devsynapse    # remove local artifacts\n```\n\nRuntime state is intentionally outside the source checkout by default:\n\n- config: `~/.config/devsynapse-ai/.env`\n- SQLite data: `~/.local/share/devsynapse-ai/data`\n- logs: `~/.local/state/devsynapse-ai/logs`\n\nPackaged desktop installs complete interactive setup inside the app on first\nlaunch. The onboarding flow configures the local admin password, DeepSeek API key\nand default repository folder before the chat workspace is available.\n\nLocal security checklist:\n\n- keep the backend bound to `127.0.0.1` unless network access is intentional;\n- keep CORS limited to local or explicitly trusted browser origins;\n- store `DEEPSEEK_API_KEY` only in runtime config or environment;\n- complete first-run admin password setup when prompted;\n- use the admin role only when unrestricted local agent execution is intended;\n- review proposed commands before confirming mutations;\n- grant project mutation permissions only where writes are expected.\n\nThe detailed local security model is documented in\n[docs/security/local-security-model.md](docs/security/local-security-model.md).\n\nSet `DEVSYNAPSE_HOME=/path/to/runtime` to keep all three under one custom directory,\nor set `DEVSYNAPSE_CONFIG_FILE`, `DEVSYNAPSE_DATA_DIR` and `DEVSYNAPSE_LOGS_DIR`\nindividually.\n\n### Manual Path\n\nThis path is still documented for Linux-like shells. On Windows, use the\npackaged desktop installer for normal use; source-checkout setup remains an\nexperimental contributor path until a tested PowerShell setup exists.\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate\nmake setup\n```\n\nAdd your DeepSeek key to the runtime config printed by `make setup`, then:\n\n```bash\nmake dev\n```\n\n### Updating\n\nExisting installs can update without rerunning the interactive installer:\n\n```bash\ndevsynapse update\n```\n\nThe updater preserves the runtime config, creates a backup of existing config\nand SQLite state when present, refreshes dependencies, applies migrations and\nrebuilds the frontend. A direct alias is also installed:\n\n```bash\nupdate-devsynapse\n```\n\nTo pin a specific published release:\n\n```bash\ndevsynapse update --version v0.7.0\n```\n\n### Manual Backend\n\n```bash\nmake run\n```\n\n### Manual Frontend\n\n```bash\ncd frontend \u0026\u0026 npm run dev\n```\n\n### Local URLs\n\n- frontend: `http://127.0.0.1:5173`\n- OpenAPI docs: `http://127.0.0.1:8000/docs`\n- health endpoint: `http://127.0.0.1:8000/health`\n\n### Screenshots\n\nCurated product screenshots are available in [docs/screenshots/README.md](docs/screenshots/README.md).\nUse-case context is documented in [docs/product/showcase.md](docs/product/showcase.md).\n\n## Main Development Commands\n\n```bash\nmake setup\nmake dev\nmake test\nmake lint\nmake script-check\nmake frontend-lint\nmake frontend-build\nmake eval-agent\nmake desktop-build\nmake verify\nmake migrate\nmake migration-status\n```\n\n## Documentation Index\n\nStart here:\n- contributor guide: [CONTRIBUTING.md](CONTRIBUTING.md)\n- agent/contributor operating guide: [AGENTS.md](AGENTS.md)\n- product positioning analysis: [DevSynapse_IA.md](DevSynapse_IA.md)\n- code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)\n- security policy: [SECURITY.md](SECURITY.md)\n- changelog: [CHANGELOG.md](CHANGELOG.md)\n- release checklist: [RELEASING.md](RELEASING.md)\n- documentation index: [docs/README.md](docs/README.md)\n\nTechnical guides:\n- product showcase: [docs/product/showcase.md](docs/product/showcase.md)\n- contributor onboarding: [docs/development/onboarding.md](docs/development/onboarding.md)\n- architecture overview: [docs/architecture/overview.md](docs/architecture/overview.md)\n- persistence and data model: [docs/architecture/data-model.md](docs/architecture/data-model.md)\n- API overview: [docs/api/overview.md](docs/api/overview.md)\n- development workflow: [docs/development/workflow.md](docs/development/workflow.md)\n- testing guide: [docs/development/testing.md](docs/development/testing.md)\n- development roadmap: [docs/development/roadmap.md](docs/development/roadmap.md)\n- runtime and delivery notes: [docs/deployment/runtime.md](docs/deployment/runtime.md)\n- local security model: [docs/security/local-security-model.md](docs/security/local-security-model.md)\n- latest release notes: [docs/releases/v0.7.0.md](docs/releases/v0.7.0.md)\n\nSupplementary references:\n- engineering guide: [README_PROFESSIONAL.md](README_PROFESSIONAL.md)\n- frontend guide: [frontend/README.md](frontend/README.md)\n\n## Roadmap\n\nThe canonical planning source is [docs/development/roadmap.md](docs/development/roadmap.md).\nIt separates completed baseline capabilities from current priorities, later work and explicitly deferred production-hardening scope.\n\n## Contribution Scope\n\nContributions are welcome for:\n- bug fixes and reliability improvements\n- documentation quality and contributor ergonomics\n- monitoring, telemetry and operational maturity\n- frontend UX improvements that preserve current backend contracts\n- security hardening and test coverage expansion\n\nBefore opening a PR, read [CONTRIBUTING.md](CONTRIBUTING.md).\nFor the shortest setup path from a new clone, read [docs/development/onboarding.md](docs/development/onboarding.md).\n\n## Security Boundary\n\nThis project executes constrained development-oriented commands, but it is not a full sandbox product. The repository should be described as a safer local execution framework, not as a formally hardened isolation system. See [SECURITY.md](SECURITY.md) and the [local security model](docs/security/local-security-model.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn1ghthill%2Fdevsynapse-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fn1ghthill%2Fdevsynapse-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn1ghthill%2Fdevsynapse-ai/lists"}