# shockwave

> Desktop notes app with a built-in AI agent, plain .md files, and free GitHub sync

- Repository: https://github.com/stephengpope/shockwave
- Category: Productivity & personal
- Stars: 218 · Forks: 48 · Language: TypeScript · License: MIT
- Experience: Beginner friendly
- Page: https://ir.adyog.com/repos/stephengpope/shockwave/

Shockwave is a notes app for people who want an AI agent working on their notes without wiring tools together themselves. Your notes stay as .md files in a folder you own. The agent reads them, keeps them in order, and can act on what's in them, such as updating a TODO file.

It has two parts. A desktop app (macOS, Windows, Linux) is what you write in. A small server you run on a cheap Linux VPS holds your notes, keys and chats, and runs the agent, so work continues when your laptop is closed. Syncing uses a GitHub repo and a personal access token, which the README says also handles sync conflicts automatically.

The README sets it apart from typical notes apps by using GitHub for sync instead of a paid service, and by building the agent in rather than asking you to run a separate coding agent. It also lists memory and self-improvement features, though it gives few details on how they work.

## What it does

- **Plain Markdown workspace**: Notes are .md files in a folder you own. The agent organizes them and can use them to complete work.
- **Free sync through GitHub**: Syncs across devices using your own GitHub repo and token, with history and automatic handling of sync conflicts.
- **Scheduled agent jobs**: Ask in plain language, for example 'every morning at 6, review yesterday's notes'. Jobs are stored in cron.json and run on the server. You can edit them by hand, pause them or run them on demand.
- **Telegram access**: Message your agent from your phone, including voice notes, photos and documents. It works on your workspace and pushes its changes. Only your user id can talk to it.
- **Runs on your own server**: An install script sets up a small VPS that keeps working while your laptop is shut, and the app upgrades the server itself.

## What you could build

- Capture ideas, projects and due dates in one place and let the agent keep them sorted.
- Schedule a nightly job that reviews the day's notes and updates a TODO.md.
- Set one-off reminders, such as a call tonight at 6:50.
- Message the agent from Telegram to have it change files in your workspace while you're away from your laptop.
- Keep the same notes in sync across several devices without paying for a sync service.

## Who it's for

Suits note-takers who want an AI agent on their notes and are comfortable renting a small Linux server and creating a GitHub token and a model provider API key.

## Get started

Download the app for your platform from the releases page, then run the install command on a Linux VPS and keep the Server URL and API key it prints. In the app, fill in the Companion, GitHub Sync and Agent Chat settings pages, then add a workspace.

```
curl -fsSL https://raw.githubusercontent.com/stephengpope/shockwave/main/api/install.sh | sh
```

Tags: notes, markdown, ai-agent, github-sync, telegram