sandesh

Sandesh (संदेश) is Sanskrit for "message": the thing carried from one person to another, whichever road it took.

Checking mail and Google Chat usually means a browser tab: a context switch, a mouse, and a page that pulls you into everything else. sandesh keeps a local copy of both, puts the unread counts in your tmux status line and opens the full screen with prefix e, laid out like sangam. It runs like lazygit: type sandesh in any terminal. And because it ships an MCP server, you can tell Claude "read today's mails" or "mail Priya that Thursday is fine".

#Features

• Mail and chat in one place: Gmail threads and Google Chat spaces and DMs, one Tab apart.
• Sections, like saved searches: Inbox, Today, Unread, Starred, or any Gmail search (from:priya newer_than:7d). Switch with h/l; each tab shows its unread count. Search with s, keep it as a section with W.
• Opens instantly, works offline: a background service keeps a local copy in sync (Gmail's change feed every minute, chat every 30 seconds), so nothing waits on Google. Reading, filtering and local search work without a network.
• Write in your editor: compose, reply, reply all and forward open $EDITOR with a header block; save and quit to review, then send.
• Undo: archive, trash, read and star are undone with z; every send waits 10 seconds first, so z cancels that too.
• Claude can use it: list, search, read, archive and draft mail, read and post in chat, through an MCP server and a --json CLI. In the screen, @ asks Claude, S summarises, D drafts a reply, T gives today's digest.
• Nothing goes out without you: an agent's send waits for your y in a popup (the same idea as anumati for root commands).
• Notifications: new inbox mail and chat DMs or mentions, through notify-send.
• Several accounts: work and personal side by side; u focuses on one.
• Safe with your login: Google's own sign-in in your browser; tokens live in the system keyring and are never printed.
• Vim keys throughout, no arrows needed.

#Install

Requirements: Linux, a Google account (Google Chat needs a Google Workspace account; a personal Gmail gets mail only). Optional: tmux for the popup and status line, secret-tool (libsecret) for the keyring, notify-send for notifications, fzf for the label picker, wl-copy or xclip for copying links, Claude Code for the AI keys.

With kosha:

kosha install sandesh

Or with the installer, which downloads the release binary into ~/.local/share/sandesh (or builds it with Go) and links ~/.local/bin/sandesh:

curl -fsSL https://raw.githubusercontent.com/Theyashsawarkar/sandesh/main/install.sh | bash

Or from source (Go 1.26+):

git clone https://github.com/Theyashsawarkar/sandesh && cd sandesh
make && sudo make install          # or: make install PREFIX=~/.local

Arch: cd packaging/arch && makepkg -si.

Update by running the installer again; install.sh --uninstall removes it.

#Getting started

Try it first on made-up mail, no Google needed:

sandesh demo

Then just run sandesh (or press prefix e in tmux). With no credentials yet it opens a setup screen in three steps. 1, the OAuth client: it asks where your client file is (Tab completes the path, Enter on a folder opens it), checks it, and copies it into ~/.config/sandesh/client.json, so the download can be deleted; a pasted JSON or a typed client ID and secret work too. 2, sign in: Enter opens Google's sign-in in your browser (Tab switches between a work account and a personal Gmail). 3, the first sync, with a progress bar, and then the inbox.

To use your own mail, sandesh needs an OAuth client of your own (Google doesn't hand out one for everyone's terminal tools). This takes about five minutes, once:

1. Open the Google Cloud console, create a project (any name), and enable the Gmail API, the Google Chat API and the People API (APIs & Services → Library).
2. OAuth consent screen: for a Workspace account choose Internal (no Google review needed; your admin may have to allow it). For a personal Gmail choose External, add yourself as a test user, then Publish it, or Google signs you out every 7 days.
3. Google Chat API → Configuration: fill in an app name, an avatar URL and a description, and turn off "interactive features". Chat's API wants this even though sandesh only acts as you.
4. Credentials → Create credentials → OAuth client ID → Desktop app, and download the JSON.

Then either run sandesh and follow the setup screen, or do the same from the command line:

sandesh auth setup ~/Downloads/client_secret_*.json
sandesh auth add work                  # opens Google's sign-in page
sandesh auth add personal --no-chat    # a personal Gmail: mail only
sandesh service install                # background sync and notifications
claude mcp add --scope user sandesh -- sandesh mcp
sandesh doctor                         # checks all of it

sandesh opens the screen.

#The screen

Sections on top, the list on the left, the selected thread or space on the right, keys at the bottom.

• Mail list: one bordered card per thread with a blank line between them: who and when, the subject, the start of the last message, and chips for the message count and labels. Unread threads have a ● on the card's edge, the selected card is drawn in the accent colour, threads picked with x show a ✓.
• Thread: the subject and its labels on top, then each message in its own card with a From / To / Date header. HTML mail is turned into terminal formatting: headings, bold and italics, lists, real tables drawn as tables, buttons, and numbered links (o and a number opens one in the browser). Layout tables and hidden preview text are dropped. Older messages fold to one line (E opens them all), and quoted replies fold away (Q shows them).
• Chat: messages grouped by sender with their initials, yours on the right in green, day separators, replies in a thread marked ↳, @mentions highlighted. i types a message right there; c writes it in your editor. Unread follows Google Chat's own read state.
• Writing: c, r, a and f open your editor. The file starts with To:, Cc:, Bcc: and Subject: lines; write under the marker line, save and quit. You then see exactly what goes out: y sends, e edits again, d saves it as a Gmail draft, n discards. An empty message is never sent. Every send waits 10 seconds; z cancels it.
• Search: / filters what's on screen as you type; s runs a Gmail search on the server and shows the result as a temporary section, W keeps it, X removes a kept one.
• Approvals: when an agent wants to send, a banner says so; A shows the message with y / e / n.

#Keys

The screen opens in normal mode: letters are commands. /, s and @ switch to typing; Enter or Esc switches back. ? shows every key.

Move and find

Act

Claude

Other

Reviewing your message (after the editor) and approving an agent's (A, or the popup):

#Files

• Download: v saves a mail's attachments or a chat's files to ~/Downloads/sandesh (SANDESH_DOWNLOADS moves it); with several, an fzf picker opens (Tab picks more, Ctrl+a all). V saves and opens them. It never overwrites: a second copy is name (2).ext. Chat files kept in Drive open in the browser instead (b). From the shell: sandesh mail save THREAD [N|all], sandesh chat save MESSAGE [N|all].
• Upload: in the mail editor, Attach: ~/report.pdf, ~/notes.txt; or + on the review screen to pick files. In chat, U picks files to post in the space. From the shell: --attach FILE (repeatable) on mail send and chat send. Up to 25 MB per message.
• What is attached is copied when you queue the send (privately, 0600), so the file you reviewed is the file that goes out. Agents can attach files too, but those sends always wait for your approval, whatever send_policy says, and the approval shows each file and where it came from. Agents save downloads only inside the downloads folder.

#Claude and other agents

sandesh doesn't embed a model. It offers tools over MCP, and whichever agent you use calls them. Add it once and every Claude Code session can use it:

claude mcp add --scope user sandesh -- sandesh mcp

Then ask in plain words:

you     read today's mails
claude  → digest → mail_read
        3 new. Priya needs a yes/no on Thursday's release by end of day.
        Arjun asked for a review on #412. Staging DB credentials rotate at 18:00.

you     tell priya we're good for thursday, cc arjun
claude  → contacts_find → mail_send
        (a popup shows the mail; you press y)
        Sent.

The @, S, D and T keys in the screen run claude -p (your ai_command) with the same server, so they use your Claude login. No API key. Any other MCP client works the same way: the server is sandesh mcp on stdio.

#Sending safely

Mail is outward-facing and hard to take back, and the mail an agent reads is written by strangers. So:

• Agents draft; you send. An agent's mail_send or chat_send waits for you. Inside tmux a popup opens on the pane the agent runs in, with the exact recipients and text: y sends, e edits it in your editor first, n declines. Outside tmux you get a notification; answer with sandesh approve or A in the screen. The agent is told what happened (sent, declined, cancelled) and nothing else.
• Every send waits undo_seconds (10) in the outbox, yours included, so z (or sandesh outbox cancel <id>, or Ctrl+c on the command line) stops it.
• Mail is data, not instructions. Everything the tools return from mail or chat is wrapped in an <untrusted> block, and the server tells the agent not to follow instructions found there.
• A recipient you've never written to always asks, whatever the policy. send_policy in the config: confirm (the default: every agent send asks), known-contacts (replies to people you've written to go straight out), allow (anything to people you've written to goes straight out). Chat messages from agents always ask.
• A log of every agent action in ~/.local/state/sandesh/agent.log.

#Command line

Every command has --help; the read commands take --json.

Options: --account NAME on most commands (default: the first account), -h, -V.

#Using it inside tmux

sandesh is a command first; the tmux plugin adds a key and a status segment. With TPM:

set -g @plugin 'Theyashsawarkar/sandesh'
set -g status-right '#{sandesh_status} %H:%M'   # 󰇮 3  󰭹 2

prefix e opens sandesh in a popup. If sandesh isn't on your PATH, the plugin builds its own copy with Go the first time.

The key carries a bind -N note, and scripts/keybindings lists the keys inside the screen as # keybind: lines, so both show up in tmux's prefix ? and in Vayu's keybinding search.

#Configuration

~/.config/sandesh/config.toml; every line is optional. sandesh config prints this:

send_policy   = "confirm"   # confirm | known-contacts | allow (see Sending safely)
undo_seconds  = 10          # every send waits this long; z cancels
mail_interval = "60s"       # how often the background sync checks Gmail
chat_interval = "30s"       # and Google Chat
initial_days  = 30          # how far back the first sync goes
max_threads   = 150         # at most this many threads on the first sync (older mail: search)
notify        = true        # desktop notifications for new mail and DMs
ai_command    = ["claude", "-p"]   # what @, S, D and T run
# editor      = "nvim"             # default: $VISUAL, $EDITOR, vi
# include     = "~/.local/state/varna/sandesh.toml"   # a theme file; its [colors] win

# Sections are the tabs on top. label: a Gmail label id (INBOX, STARRED,
# UNREAD, or a label's id), query: a Gmail search run on the server,
# today: only threads with mail from today.
[[section]]
name  = "Inbox"
label = "INBOX"

[[section]]
name  = "GitHub"
query = "from:notifications@github.com newer_than:14d"

[colors]           # Catppuccin Mocha by default
accent  = "#74c7ec"
accent2 = "#cba6f7"

Colours follow varna's desktop theme (~/.local/state/varna/palette.json) and change live when it does; anything set under [colors] wins. Colour names: accent, accent2, text, subtle, muted, surface, border, base, mantle, green, yellow, red, blue, peach. With varna, point include at the file it writes and the screen follows your theme.

#Files and environment

SANDESH_HOME puts all of sandesh's files under one folder (tests and demo use it). SANDESH_GOOGLE_URL sends every API call to a fake Google (the test suite's). The usual XDG_* variables are respected.

#How it works

• One local copy, many front ends. sandesh daemon (the systemd user unit) follows Gmail's change feed (history.list) every minute and checks Google Chat spaces with new activity every 30 seconds, storing everything in SQLite with full-text search. The screen, the CLI and the MCP server read that copy, so they open instantly; the screen syncs on its own only when the daemon isn't running, and right after you change something. A lock lets only one process sync an account at a time, and Gmail requests are paced well under Google's per-minute limit.
• One send path. Every send, from you or an agent, becomes an outbox row: approval (an agent's, waiting for you) → queued (the undo window) → claimed by whichever process gets there first → sent or failed. Claiming is one atomic update, so a message is sent once even with the daemon, the screen and the MCP server all running.
• Google's APIs, not IMAP. Chat has no IMAP, so sign-in is needed anyway; the Gmail API also gives real labels, threads, drafts that show up on your phone, and Gmail's search syntax. Sign-in is the loopback OAuth flow with PKCE. Scopes: gmail.modify, Chat's spaces, messages, memberships and read state, directory.readonly (names for chat senders) and profile.
• Written in Go: one static binary, Bubble Tea for the screen, the official MCP Go SDK, pure-Go SQLite.

Design decisions are recorded in docs/adr.

#Troubleshooting

• sandesh doctor checks the OAuth client, each account's sign-in and last sync, the background service, the tmux key and the Claude Code MCP server.
• "Google said no: … has not been used in project": enable that API (Gmail, Chat or People) in the Cloud console for your project.
• Chat fails, mail works: Google Chat's API needs a Workspace account and the Chat API's Configuration page filled in. For a personal Gmail: sandesh auth remove personal && sandesh auth add personal --no-chat.
• "access blocked" or "admin_policy_enforced" on sign-in: your Workspace admin has to allow the app (Admin console → Security → API controls).
• Signed out every week: the consent screen is External and still in Testing; publish it.
• Logs: journalctl --user -u sandesh -f.

#Contributing

make check runs what CI runs: go vet, gofmt, ShellCheck, the tests (against a fake Google, internal/fake) and the website check. Keys live in internal/tui/keys.go; after changing one, run go test ./internal/tui -update (it rewrites scripts/keybindings) and update the tables above. Every change gets a CHANGELOG entry.

#Roadmap

• Attachments: save and open.
• Gmail and Chat push (Pub/Sub, Workspace Events) instead of polling.
• A Vyom glance panel and a waybar module reading sandesh status --json.
• Calendar invites: accept and decline from the preview.

#License

MIT