Work Assistant

Email becomes a local archive usable by a person or by an intelligent agent.

Provider-independent · Multiple mailboxes · CLI · MCP · Human review

Start with the demo · Use it with an agent · Understand how it protects data · Project status

What Work Assistant is

Work Assistant is a local system for organizing and using email with intelligent tools.

The system fetches messages from one or more mailboxes, normalizes them, and stores them in a local SQLite archive. From that archive it rebuilds a view of contacts and interactions. An individual can use the system from the command line. An agent, such as Codex or Claude, can use it through the MCP protocol.

Work Assistant is not a traditional email client, nor is it a simple skill:

• the core handles accounts, the archive, checks, and proposed content;

• the CLI lets an individual use the core without a model;

• the MCP server offers structured tools to agents;

• the skill teaches the agent how to use those tools within authorized limits;

• an adapter connects a specific email service to the core.

The public core does not send email. Drafted replies remain local candidates until a separate, authorized action is taken.

Related MCP server: Mailing Manager MCP

Why it exists

A mailbox contains more than individual messages. It contains conversations, people, attachments, decisions, and pending activities. Standard clients do well at showing current email but make it difficult to reuse this history as operational knowledge.

Work Assistant separates three layers:

1. Local archive: what has been ingested is kept and its integrity is checked.

2. Knowledge view: it reconstructs contacts and interactions from the archive. It is derived and can be regenerated.

3. Agent surface: it lets a model search, read, and prepare content through controlled operations.

The knowledge view is not the original source and does not, by itself, constitute a verified backup. A real backup also requires copying, retention, verification, and recovery-trial practice.

How it works

flowchart LR
  Persona[Persona] --> Agente[Agente intelligente]
  Agente -->|strumenti MCP| Gateway[Gateway MCP]
  Gateway -->|IPC locale autenticato| Broker[Broker locale]
  Broker --> Archivio[(Archivio locale)]
  Broker --> Vista[Vista di conoscenza]
  Broker --> Candidati[Candidati di risposta]
  Adapter[Adapter del provider] --> Broker

  classDef paper fill:#f7f2e7,stroke:#294b37,color:#172019;
  classDef sage fill:#dce8d8,stroke:#294b37,color:#172019;
  classDef accent fill:#aa593e,stroke:#aa593e,color:#f7f2e7;
  class Persona,Archivio,Vista,Candidati paper;
  class Gateway,Broker,Adapter sage;
  class Agente accent;

The broker is the trust boundary. It reads plaintext data, applies the pseudonymization rule, and returns to the gateway only a declared schema. Provider identifiers become opaque references. Unrecognized metadata does not cross the boundary.

Try the demo

The demo uses only synthetic identities and messages. It requires no credentials or a real mailbox.

Requirements

• Python 3.11 or later;

• Git;

• macOS, Linux, or Windows.

1. Install the project

git clone https://github.com/Wulfgardr/work-assistant.git
cd work-assistant
python3 -m venv .venv

Activate the environment on macOS or Linux:

source .venv/bin/activate

On Windows PowerShell:

.venv\Scripts\Activate.ps1

Install Work Assistant:

python -m pip install .

2. Create the configuration

work-assistant --config work-assistant.toml init

The command creates an operating-system-specific data folder. Archive, keys, and identity records are not placed in the repository.

3. Load the demo mailboxes

work-assistant --config work-assistant.toml sync --account personal
work-assistant --config work-assistant.toml sync --account team
work-assistant --config work-assistant.toml list
work-assistant --config work-assistant.toml knowledge
work-assistant --config work-assistant.toml verify

The verify command checks SQLite integrity and message hashes. It does not prove that a backup can be restored.

Use Work Assistant with an agent

Codex, Claude, and other MCP clients use the same surface. The model is not embedded in the CLI.

Install MCP support:

python -m pip install '.[mcp]'

1. Start the local broker

Open a trusted local terminal and start:

work-assistant --config work-assistant.toml broker

The broker must remain active. If it is not available, the MCP gateway stops instead of reading the archive directly.

In a second terminal, retrieve the two needed paths:

work-assistant --config work-assistant.toml broker-info

2. Configure the server in Codex

Replace the two placeholders with the values from broker-info:

codex mcp add work-assistant -- \
  "$PWD/.venv/bin/work-assistant" \
  mcp \
  --broker-address '<BROKER_ADDRESS>' \
  --broker-auth-file '<BROKER_AUTH_FILE>'

On Windows, use .venv\Scripts\work-assistant.exe.

Example request:

Use Work Assistant. Check the privacy mode, sync the personal mailbox, show the latest messages, and prepare a reply candidate. Do not send anything.

The report

The optional skill is in skills/work-assistant. The skill adds operating rules, but does not replace the MCP server.

3. Link the server in Claude Code

claude mcp add work-assistant -- \
  "$PWD/.venv/bin/work-assistant" \
  mcp \
  --broker-address '<BROKER_ADDRESS>' \
  --broker-auth-file '<BROKER_AUTH_FILE>'

For Claude Desktop, configure an equivalent stdio server:

{
  "mcpServers": {
    "work-assistant": {
      "command": "/percorso/assoluto/work-assistant/.venv/bin/work-assistant",
      "args": [
        "mcp",
        "--broker-address",
        "<BROKER_ADDRESS>",
        "--broker-auth-file",
        "<BROKER_AUTH_FILE>"
      ]
    }
  }
}

Use the CLI without an agent

The CLI is deterministic: it uses no model and does not interpret natural-language requests.

work-assistant --config work-assistant.toml list --account personal --limit 10
work-assistant --config work-assistant.toml show --account personal --id p-001

To save a local reply candidate:

printf 'Grazie. Verifico il documento entro venerdì.\n' > risposta.txt
work-assistant --config work-assistant.toml draft-candidate \
  --account personal \
  --to sam@example.test \
  --subject 'Re: Revisione del progetto' \
  --in-reply-to p-001 \
  --body-file risposta.txt

The result includes sent: false. No content is written to the provider.

An agent with a terminal must use MCP. It must not read SQLite directly or plaintext CLI output.

Configure multiple mailboxes

Each table under [accounts] describes an independent mailbox:

schema_version = 1
data_dir = "/percorso/esterno/al/repository"

[privacy]
mode = "all"
default_action = "pseudonymize"

[accounts.personal]
provider = "demo"
source = "./examples/demo-mailbox.jsonl"
address = "alex@example.test"

[accounts.team]
provider = "demo"
source = "./examples/team-mailbox.jsonl"
address = "team@example.test"

2. Pushing to a repository

The repository contains only the demo adapter. Real adapters must implement the contract described in docs/PROVIDER_ADAPTERS.md.

Zimbra and Carbonio

The public version includes local onboarding to prepare a Zimbra or Carbonio session from a HAR file. The production Zimbra adapter is not included.

sequenceDiagram
  participant A as Agente
  participant P as Persona
  participant B as Browser
  participant C as CLI locale
  A->>P: Spiega i passaggi e controlla lo stato
  P->>B: Esegue login e autenticazione a due fattori
  P->>C: Importa localmente il file HAR
  C-->>P: Conferma solo nomi dei cookie e stato
  Note over A,C: Password, OTP, HAR e valori dei cookie non entrano nel modello

The local command is:

work-assistant --config work-assistant.toml import-zimbra-har \
  --account work \
  --har /percorso/locale/session.har

The command does not delete the HAR file. After checking, move or delete the report using a procedure appropriate to its sensitive content.

How it protects data

Work Assistant offers three modes:

Sample of a "Everything":

[privacy]
mode = "selective"
default_action = "pseudonymize"

[[privacy.sender_rules]]
pattern = "newsletter@example.test"
action = "allow_raw"

[[privacy.sender_rules]]
pattern = "*@sensitive.example"
action = "pseudonymize"

The agent response contains only an opaque identifier of the rule, not its literal value.

The optional identity registry sits, by default, in <data_dir>/privacy/entities.json. On POSIX systems it must be owned by the user and have permissions 0600.

Pseudonymization is reversible and does not guarantee anonymity. Rare details, context, writing style, or undefined terms can identify a person.

For the broker to be a real boundary, the data folder must remain outside any view second-level level that the agent can read. The broker rejects it by default unless an explicit, unsafe override is provided for controlled demos only.

Read SECURITY.md before writing real messages.

Support

Daybreak Security Review

On 24 August 2025, a Daybreak review analyzed the broker, pseudonymization, IPC, and MCP. The review found seven issues: one of medium severity and six of low severity.

Version 0.3.0 resolves these:

• data and keys outside the repository by default;

• broker refuses to start if the protected vault is inside the agent workstation;

• external identity registry with permission checks;

• closed-face MCP schema, opaque references, and provider meta-mastectors excluded;

• opaque identifiers for selective rules;

• security fixed pool and idle timeout;

• end-to-end timeout on connection, authentication, request, and response;

The report, evidence, and leftover limitations are in docs/security/DAYBREAK-REVIEW.md.

Backup and recovery

Work Assistant stores normalized messages with their hashes. Checking is easy, but this does not automatically make it a durable backup.

To claim a verified backup, you must define and prove:

• which messages and attachments are included;

• security and key management;

• frequency, retention, and options;

• hash checking;

• restore procedure on an isolated environment;

• expected vs restored content provenance.

It never issues

The verify command checks the current archive. It does not perform a recovery.

Where the project stands

Work Assistant is an alpha project.

Available:

• provider-independent core;

• multi-mailbox configuration;

• automotive demo adapter;

• SQLite archive with hash;

• local view of contacts and interactions;

• CLI;

• MCP gateway and broker;

• reversible pseudonyms;

• agent skills;

• initial setup for Zimbra and Carbonio.

It's not:

• production adapters for actual providers;

• no catch processes;

• honor;

• complete backup and recovery test;

• pseudonymization of attachment binary content;

• anonymity guarantee.

Be

python -m pip install '.[dev,mcp]'
pytest
python scripts/privacy_check.py
work-assistant benchmark-privacy --iterations 50

Use only synthetic data in code, tests, mockups, issues, and pull requests. Read CONTRIBUTING.md for the project process.

License

Work Assistant is released under the MIT license.