narad 0.1.0

A lightweight personal CRM for the command line and local browser.

Narad

Narad is a lightweight, local-first personal CRM for people who want a fast way to remember contacts, conversations, and follow-ups without adopting a sales platform.

It gives you a Python CLI, a compact local browser UI, and a SQLite database on your machine. Use it to track people, organizations, relationship notes, follow-up tasks, contact sources, interaction channels, tags, and full-text search.

Why Narad?

Most CRMs are built for teams, pipelines, dashboards, and reporting. Narad is for a single user (including local agents) who wants to keep context:

• Consultants tracking client outreach and follow-ups

• Sales reps managing relationships in a lightweight flow

• Solo founders organizing contacts and partnerships

• Who did I meet?

• Where did this relationship come from?

• What did we talk about last time?

• What should I follow up on today?

• Can I find that note from LinkedIn, WhatsApp, a call, or a conference?

Narad keeps that loop small, searchable, and local.

Features

• Contacts with name, email, phone, title, location, source, company, and tags.
• Organizations linked to contacts.
• Relationship notes and interactions with optional channel metadata.
• Follow-up tasks with due dates and completion state.
• today view for overdue tasks, tasks due today, and recent notes.
• FTS5 search across contacts, organizations, notes, tasks, sources, channels, and tags.
• Local browser UI served by FastAPI at http://127.0.0.1:8765.
• Plain SQLite storage under your own home directory.

Contact source means where the relationship originated, such as linkedin, tea shop, twitter, referral, or conference.

Interaction channel means where a specific note or event happened, such as call, email, whatsapp, linkedin, twitter, or in-person.

Quick Start

Narad requires Python 3.12 or newer.

Install from a checkout:

git clone https://github.com/gauravvgat/narad.git
cd narad
uv tool install .

Then initialize your local database:

narad init
narad today

For contributor-style local development, use uv sync and run commands with uv run narad ... instead.

Usage

Create a small relationship graph:

narad add org "Acme Labs" --website https://acme.example --tag investor
narad add contact "Asha Rao" --company "Acme Labs" --email [e-mail] --source linkedin --tag warm
narad add note "Discussed pilot timeline" --contact "Asha" --channel whatsapp
narad add task "Send pilot proposal" --due today --contact "Asha"

Keep it current:

narad edit contact 1 --email [e-mail] --source conference
narad list contacts --tag warm
narad list tasks --status open
narad search "pilot"
narad show 1
narad done 1

Open the local web UI:

narad serve

Useful commands:

• narad init: create the Narad home directory and initialize the database.
• narad today: show overdue tasks, tasks due today, and recent notes.
• narad list contacts: list contacts, optionally filtered by tag.
• narad list tasks: list tasks by open, done, or all.
• narad search: search across your CRM.
• narad show: show one contact profile with tasks and timeline.
• narad serve: start the local browser UI.
• narad path: print the configured home and database paths.
• narad search-reindex: rebuild the full-text search index.

Storage And Privacy

By default, Narad stores data in:

~/.narad/narad.db

For isolated runs, demos, tests, or agent sandboxes, override the paths:

export NARAD_HOME=/tmp/narad-home
export NARAD_DB=/tmp/narad-home/narad.db

Narad is local-first and single-user in v1. The web UI binds to 127.0.0.1 by default and does not include accounts, teams, permissions, or remote sync.

Development

Install dependencies and run checks:

uv sync
uv run pytest
uv run ruff check .
uv run pre-commit install

The pre-commit hook runs ruff and pytest.

Project stack:

• Python package management: uv
• CLI: Typer and Rich
• Web UI: FastAPI, Jinja templates, and plain CSS
• Database: SQLite through Python sqlite3
• Tests: pytest
• Lint: ruff

Before changing behavior, read:

• AGENTS.md
• memory/index.md
• relevant memory/areas/*.md
• relevant user_stories/*.md

The repo memory and user stories are part of the project documentation, not generated scratch notes.

Maintainer Release

Before publishing, run the checks and build the release artifacts:

uv run pytest
uv run ruff check .
uv build --no-sources

This creates a source distribution and wheel under dist/.

The wheel includes only the runtime narad package, including the web UI templates and CSS. The source distribution is intentionally trimmed to source files and public package metadata:

• src/narad/
• README.md
• LICENSE
• pyproject.toml

Repo-local memory, user stories, artifacts, tests, and uv.lock are not shipped in distribution artifacts.

Publish to PyPI after the project is configured:

uv publish

For automated releases, prefer PyPI Trusted Publishing from GitHub Actions over long-lived PyPI tokens.

Contributing

Contributions are welcome, especially when they keep Narad small and useful.

Good first areas:

• Improve CLI ergonomics.
• Tighten the local web UI.
• Add focused tests for store, CLI, or web behavior.
• Improve import/export workflows.
• Clarify docs for real personal CRM use cases.

Design principles:

• Keep source code as the source of truth.
• Keep CLI and web behavior aligned through narad.store.
• Prefer simple SQLite-backed behavior over premature platform features.
• Do not touch a user's real ~/.narad/narad.db in tests.
• Use NARAD_HOME and NARAD_DB for isolated test data.

AI Agent Usage

Agents should treat Narad as the user's local personal CRM and prefer the CLI over direct SQLite writes.

Before adding a likely duplicate contact, search first:

narad search "asha acme"
narad show 1

Then record structured context through the CLI:

narad add contact "Asha Rao" --company "Acme Labs" --source linkedin --tag warm
narad add note "Discussed pilot timeline" --contact "Asha" --channel whatsapp
narad add task "Send pilot proposal" --due tomorrow --contact "Asha"
narad edit contact 1 --source conference --tag champion
narad done 3

Agent guidelines:

• Use contact IDs from narad search, narad list contacts, or narad show when a name is ambiguous.
• Store relationship origin in contact --source.
• Store event medium in note --channel.
• Record follow-ups as tasks instead of burying them only in note text.
• Use NARAD_HOME and NARAD_DB for sandboxed runs.

Roadmap

Near-term ideas:

• Add practical import/export commands.
• Add backup helpers.
• Improve filtering and editing flows in the web UI.

Narad is intentionally not trying to become an enterprise CRM. Sync, hosted multi-user access, and advanced reporting can wait until they clearly earn their complexity.

License

Narad is released under the MIT License. See LICENSE.