Skip to content

caporro/devsync

BranchesTags

Repository files navigation

Devsync - Open-source Team Context Engine for human and AI teams

Devsync is an open-source, self-hosted Team Context Engine that keeps human teams, assistants, automations, and AI agents aligned through a local-first, Git-versioned project memory.

It turns scattered updates, decisions, resources, tasks, work files, and AI instructions into shared operational context stored in readable Markdown and JSON files.

devsync

Why Devsync

AI makes teams faster, but faster output creates a new bottleneck: keeping everyone aligned on the real state of the work.

Teams already have chat, tickets, docs, repositories, AI chats, and meetings. Each tool holds a fragment of truth, but none of them becomes a shared operational memory for people and agents.

Devsync gives the project a durable context layer:

  • updates become activity log;
  • long material becomes resources;
  • next actions become tasks;
  • generated output becomes work files;
  • Assistant and automations operate on the same project memory;
  • external AI clients can access context through MCP;
  • the whole vault stays readable, portable, and Git-versioned.

Getting Started / Try

Quick Docker trial:

docker run -p 4000:4000 \
  -v devsync-data:/data \
  -e AUTH_MODE=none \
  caporro/devsync:latest

Open:

http://127.0.0.1:4000

AUTH_MODE=none is only for private local use. For deployment, use password auth.

Full configuration: docs/reference/env-vars.md.

docker hub images: https://hub.docker.com/r/caporro/devsync

screen edit md

Core Workflow

Devsync starts from a simple idea: teams should capture context while work happens, not reconstruct it later from fragments.

The workflow is:

  1. Capture updates, decisions, tasks, resources, files, and outputs.
  2. Structure them around a project/topic in a readable vault.
  3. Retrieve the current state through UI, files, Assistant, automations, or MCP.
  4. Act by creating tasks, updating work files, summarizing state, or running automations.

Practical rules:

  • log = short timeline;
  • resource = useful input/source material;
  • tasks = operational work;
  • work = produced or refined output;
  • docs = team knowledge;
  • vault = data source.

Who It Is For

Devsync is built first for:

  • AI-heavy software teams that need less status chasing and better shared context;
  • solo founders managing multiple projects with AI agents;
  • technical teams that prefer self-hosted, open-source, filesystem-first tools;
  • teams that want AI assistants and automations to work on real project context, not copied prompts.

It can later fit any team that works by project and needs shared context between people and AI.

What Devsync Is Not

Devsync is not another wiki, another AI chat, or a Jira replacement.

It does not need to replace your whole stack. It gives your stack a shared context layer.

  • Use chat for conversation.
  • Use issue trackers for workflow.
  • Use Devsync for operational memory.

Local Run

Build + start:

npm install
npm run build
npm start

Open:

http://127.0.0.1:4000

Local config:

cp .env.example .env

Minimum:

AUTH_MODE=none
DEVSYNC_VAULT_NAME=devsync-vault
DEVSYNC_AGENT_MODEL=openai:gpt-4.1-mini
OPENAI_API_KEY=sk-...

Run Developing

Backend:

npm run dev:server

Override vault from CLI:

npm run dev:server -- --vault another-vault

Frontend:

npm run dev:web

Use .env in the repository root.

Production Deploy

For production, use only the Docker image, persistent storage, password auth, and HTTPS.

Generate a password hash:

node scripts/hash-password.mjs

Run:

docker run -d \
  --name devsync \
  -p 4000:4000 \
  -v devsync-data:/data \
  -e AUTH_MODE=password \
  -e 'AUTH_USERS=email@example.com|Name|scrypt$...' \
  -e AUTH_SESSION_SECRET='change-me-to-a-long-random-string-at-least-32-chars' \
  -e AUTH_COOKIE_SECURE=true \
  -e OPENAI_API_KEY='sk-...' \
  caporro/devsync:0.1.25

Notes:

  • always mount persistent storage on /data;
  • use AUTH_COOKIE_SECURE=true only behind HTTPS;
  • put Devsync behind a reverse proxy if publicly exposed;
  • do not use AUTH_MODE=none on shared servers.

Docker Compose:

docker compose up -d

Configure

Main variables:

PORT=4000
HOST=0.0.0.0
DEVSYNC_VAULT_NAME=devsync-vault
DEVSYNC_DATA_ROOT=/data
AUTH_MODE=password
AUTH_USERS=email@example.com|Name|scrypt$...
AUTH_SESSION_SECRET=change-me-to-a-long-random-string-at-least-32-chars
AUTH_COOKIE_SECURE=true

User format:

email|display name|password hash

Multiple users:

AUTH_USERS=claudio@example.com|Claudio|scrypt$...,mario@example.com|Mario|scrypt$...

AI provider:

DEVSYNC_AGENT_MODEL=openai:gpt-4.1-mini
OPENAI_API_KEY=sk-...

OpenAI-compatible:

DEVSYNC_AGENT_MODEL=openai-compatible:model-name
OPENAI_API_KEY=...
OPENAI_BASE_URL=https://api.example.com/v1

Other supported providers:

DEVSYNC_AGENT_MODEL=anthropic:claude-sonnet-4-5-20250929
ANTHROPIC_API_KEY=...

DEVSYNC_AGENT_MODEL=google-genai:gemini-2.5-flash
GOOGLE_API_KEY=...

DEVSYNC_AGENT_MODEL=mistralai:mistral-large-latest
MISTRAL_API_KEY=...

DEVSYNC_AGENT_MODEL=groq:openai/gpt-oss-120b
GROQ_API_KEY=...

Git vault sync:

DEVSYNC_VAULT_REPO_URL=https://github.com/org/devsync-vault.git
DEVSYNC_GIT_USERNAME=oauth2
DEVSYNC_GIT_TOKEN=...
DEVSYNC_GIT_COMMIT_NAME=Devsync
DEVSYNC_GIT_COMMIT_EMAIL=devsync@example.invalid

Full reference: docs/reference/env-vars.md.

Why Filesystem First

The vault is the source of truth.

This is a product decision, not only a technical one:

  • your context stays in files your team owns;
  • Markdown and JSON are readable by humans, agents, editors, shell tools, and Git;
  • Git can version, diff, sync, and back up the project memory;
  • Assistant, automations, and MCP can work on the same underlying context;
  • the data remains usable outside the Devsync UI;
  • no database is required until a derived index or enterprise layer is truly needed.

No database does not mean no structure. It means the structure lives in files.

Vault Structure

Default local path:

data/devsync-vault/

Default Docker paths:

/data/devsync-vault/
/data/auth/
/data/system/
/data/users/

Layout:

data/<vault>/
  README.md
  assistant.md
  vault-plan.json
  config/
    skills.json
  skills/
  automations/
  docs/
  projects/
    project-id/
      project.json
      README.md
      assistant.md
      automations/
      resources/
      tasks/
      logs/
      work/

Assistant chat history is runtime data, not vault data:

data/runtime/<vault>/chats/

Meaning:

  • project folder name is the project id/name shown in the UI;
  • project.json: project metadata only; name is legacy and ignored;
  • README.md: main notes;
  • logs/: append-only activity log;
  • resources/: raw material, inputs, sources, uploads, links, notes, images, PDFs, Excalidraw files;
  • tasks/: tasks, owner, deadline, and index;
  • work/: produced or refined material from Assistant, automations, or people;
  • assistant.md: AI instructions;
  • config/skills.json: disabled system skill config;
  • skills/: vault Assistant skills;
  • automations/: automations.

The vault can be versioned with Git. Git sync helps, but it does not replace a full backup.

Detailed layout: docs/reference/vault-layout.md.

Automate

Devsync automates work through Assistant, skills, and automations.

Global Assistant:

data/<vault>/assistant.md

Project Assistant:

data/<vault>/projects/<project>/assistant.md

Instruction order:

base Devsync
+ vault assistant
+ project assistant
+ skill catalog
+ chat history

Vault skill config:

{
  "disabledSystemSkills": []
}

Vault skill structure:

data/<vault>/skills/<skill-name>/SKILL.md

Assistant resolution details: docs/reference/assistant.md.

Example assistant.md:

---
title: "Project Operator"
model: openai:gpt-4.1-mini
tools:
  - filesystem
  - save_generated_markdown
  - append_activity_log
read:
  - "**/*"
write:
  - work/**
  - tasks/**
---
Work on the project. Write long outputs to work/.

Automation:

---
title: "Update Situation"
trigger: manual
tools:
  - filesystem
read:
  - README.md
  - resources/**
  - logs/**
write:
  - work/situation.md
---
Update work/situation.md with status, blockers, and next actions.

Supported triggers:

  • manual;
  • event;
  • schedule.

Supported events:

  • project_log.added;
  • artifact.added;
  • task.added.

Schedule uses 5-field cron:

trigger: schedule
cron: "0 18 * * 1-5"

Main tools:

  • filesystem;
  • append_activity_log;
  • save_generated_markdown;
  • send_email_ses;
  • list_tasks;
  • read_task;
  • create_task;
  • update_task;
  • toggle_task;
  • delete_task.

MCP

Devsync exposes MCP for external AI clients.

Endpoint:

/mcp

Local stdio:

npm run mcp

User token:

  1. open the user menu;
  2. create an MCP token;
  3. configure the client with Authorization: Bearer devsync_mcp_...;
  4. revoke the token when it is no longer needed.

Codex example:

export DEVSYNC_MCP_TOKEN=devsync_mcp_...
codex mcp add devsync --url http://127.0.0.1:4000/mcp --bearer-token-env-var DEVSYNC_MCP_TOKEN

MCP tools:

  • list_projects;
  • get_project;
  • search_files;
  • read_file;
  • list_tasks;
  • read_task;
  • create_task;
  • update_task;
  • toggle_task;
  • delete_task.

Operate

Healthcheck:

curl http://127.0.0.1:4000/api/health

Expected response:

{ "ok": true, "authMode": "password" }

Docker logs:

docker logs -f devsync

Minimum backup:

data/

System Log records events such as:

  • project creation;
  • metadata changes;
  • resource creation;
  • mention creation;
  • automation runs;
  • git pull/push.

Mentions use Markdown links:

@[Claudio](devsync:user:claudio)

Mention notifications are stored as mention.created events in data/system/events.ndjson. Unread state is per user only:

data/users/<userId>/inbox-state.json

Recommended upgrade flow:

  1. back up the vault;
  2. update the image;
  3. restart;
  4. check the healthcheck;
  5. verify login;
  6. open a project;
  7. test Assistant if configured.

Credits

Devsync uses and thanks:

  • Node.js;
  • Fastify;
  • React;
  • Vite;
  • TypeScript;
  • Tailwind CSS;
  • shadcn/radix-ui;
  • TanStack Query;
  • Hugeicons;
  • Excalidraw;
  • Milkdown/Crepe;
  • SVAR Gantt;
  • LangChain;
  • DeepAgents;
  • Model Context Protocol SDK.

License

MIT. See LICENSE.

Contributing

Contributions are welcome: PRs, issues, ideas, discussions, bug reports, documentation, automation examples, plugins, and integrations.

Project philosophy:

  • KISS;
  • YAGNI;
  • filesystem-first;
  • minimal out-of-the-box functionality;
  • no database until it is truly needed;
  • advanced features should preferably live in plugins;
  • operational UI, not decorative UI.

We are also looking for sponsors and feedback from teams that use AI every day on real projects.

See CONTRIBUTING.md.

Security

Report vulnerabilities through SECURITY.md.

Do not open public issues with secrets, reproducible exploits, or sensitive data.

Responsibility

Devsync is provided "as is", without warranties. Whoever installs and uses it is responsible for configuration, security, backups, permissions, inserted data, AI outputs, and production use.

Outputs produced by Assistant, automations, or AI models must be reviewed before being used for operational, legal, financial, security, or production decisions.

Next

Possible directions:

  • Electron app;
  • plugin system;
  • subscription and conversation imports from tools such as Codex, Claude, and similar products;
  • optional external integrations;
  • marketplace/community automations;
  • self-hosted deployment hardening.

About

Team Context Engine

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

13 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages