Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
182 lines (134 loc) · 9.65 KB

CONTRIBUTING.md

File metadata and controls

182 lines (134 loc) · 9.65 KB
Raw

Contributing to Sentient

Thanks for helping. Sentient is a personal assistant that runs on your own computer, and it is built in the open. This guide gets you from zero to a merged pull request.

You never need our keys

Sentient v3 has no .env file and no shared API keys. Please do not ask for them: there is nothing to share.

  • To run the app, use a free local model through Ollama, or paste your own provider key (Anthropic, OpenAI, Gemini and others) in Settings → Models. Keys stay in your own system keychain.
  • To run the tests, you need nothing at all. Every test uses a scripted fake model and no network.
  • Integrations (Gmail, Slack, Notion, Telegram...) connect with your own accounts from inside the app, and each one has step-by-step setup instructions. Their tests use mocked APIs.

If something only works with a key you don't have, that is a bug in our tests or docs: open an issue.

Get it running

You need Python 3.12 with uv, Node 22, and optionally Ollama.

git clone https://github.com/<you>/Sentient.git && cd Sentient
uv venv .venv --python 3.12
uv pip install --python .venv/Scripts/python.exe -e ".[dev,voice]"   # macOS/Linux: .venv/bin/python
cd desktop && npm install && npm run dev

The window starts the engine for you and walks you through setup. More detail, including how to run the engine on its own and how to capture screenshots, is in docs/DEVELOPING.md.

How we work

We use GitHub flow:

  1. Find or open an issue, then claim it. Look for good first issue and help wanted. Comment /assign on a free issue and a bot assigns it to you, so nobody else starts the same work. For anything bigger than a small fix, also say how you plan to do it so we can agree on the approach. Small fixes and docs need no issue.
  2. Fork, then branch from main. Name the branch after what it does, for example fix/telegram-long-messages or feat/outlook-integration.
  3. Keep the pull request small and focused. One change per PR is much faster to review.
  4. Open the PR against main. The checks below run automatically, also on forks.
  5. A maintainer reviews it. One approval and green checks are enough. We squash-merge, so the PR title becomes the commit message.

There are no long-lived development or staging branches. main is always the latest working version, and releases are tags on main.

Claiming an issue

Comment on the issue with just one line:

  • /assign assigns the issue to you, if nobody has it yet. If someone does, the bot tells you who, so you can pick another issue or offer to team up.
  • /unassign hands it back, if it is yours. No explanation needed, and thanks for saying so.

Try to open a pull request (a draft is fine) within a week. If you need longer, just comment on the issue.

If things go quiet

Life happens, and that's fine. To keep issues moving for everyone, a bot checks once a day:

  • A claimed issue with no pull request and no comment from you for 14 days gets a friendly ping. After 21 days (and at least a week after the ping), you are unassigned so someone else can pick it up. You can /assign it again any time while it is free.
  • A pull request where we asked for changes and nothing has happened for 7 days gets the waiting on author label and one gentle reminder (only ever one per pull request). Pushing a commit or replying removes the label. After 21 days (and at least a week after the reminder) we close it with a thank-you, and unassign you from its issue. You can reopen it whenever you have time, or comment and we will reopen it for you.

Draft pull requests are never touched, and the clock only runs while we are waiting on you, never while you are waiting on us.

We do the chores

You bring the change; we take care of the busywork around it, so a pull request never stalls on housekeeping.

  • What we may do on your branch: merge main into it, resolve conflicts, rename or add a changelog file, fix lint or formatting, re-run checks, and make tiny fixes a review asked for.
  • What we always do: say exactly what we pushed in a comment, never force-push, and only push when Allow edits by maintainers is ticked on your pull request (it is by default).
  • What stays yours: anything that changes how your code behaves or how it is designed comes back to you as a review, never as a surprise commit.
  • Your branch doesn't need to be up to date to merge. The merge queue tests your change on top of the latest main before it lands. If you want main merged in anyway, comment /update on the pull request: a bot tries to merge it in (a merge, never a rebase) and tells you what happened. If it can't update your branch, it shows you how to do it with GitHub's Update branch button. If there are conflicts, it lists the files and labels the pull request needs update, and a maintainer resolves them for you.

PR titles

Use Conventional Commits with an area, because the title becomes the commit message:

feat(channels): send Telegram replies as voice notes
fix(browser): keep refs stable after a scroll
docs(nodes): document the battery event

Types: feat, fix, docs, refactor, test, perf, chore. Areas match the folders below.

What the checks run

Run the same things locally before you push:

.venv/Scripts/ruff.exe check sentient tests            # lint (macOS/Linux: .venv/bin/ruff)
.venv/Scripts/python.exe -m pytest -q                  # engine tests, or one folder: pytest tests/tasks
cd desktop && npm run typecheck && npm run build       # desktop

The full engine suite takes a few minutes. While you work, run just the folder you touched.

A good pull request

  • Says what changed and why, and links the issue (Closes #123).
  • Adds or updates tests. Bug fixes come with a test that failed before the fix.
  • Updates docs/API.md in the same PR when it changes anything the desktop app and the engine exchange. The contract comes first.
  • Adds a changelog entry when people using Sentient will notice the change: one file, changes/<issue or PR number>.<type>.md, such as changes/412.fixed.md, with a short bold first sentence in plain language. Don't edit CHANGELOG.md itself; the entries are joined into it at release time, so pull requests don't collide there. Types and examples are in changes/README.md. The "Changelog entry" check asks for one when you change sentient/, desktop/src/ or packaging/; for changes nobody will notice (tests, refactoring, tooling) a maintainer adds the no changelog label instead.
  • Includes a screenshot or short clip for visible UI changes.
  • Keeps the product rules: no login or accounts, keys only in the keychain, every tool declares a risk, and sending, deleting, buying or running code asks the user first.

Where things live

Area Folder Notes
Engine core sentient/agent, sentient/llm, sentient/store, sentient/tools, sentient/gateway Agent loop, model roles, approvals, SQLite
Tasks sentient/tasks Long-running, scheduled, triggered and watcher tasks
Memory sentient/memory Facts, user model, nightly consolidation
Proactivity and skills sentient/proactivity, sentient/evolution, sentient/skills Suggestions, self-improving skills
Integrations sentient/integrations One plugin per app; start from an existing one
Channels sentient/channels Telegram, Discord
Devices sentient/nodes, firmware/, docs/NODES.md Phones, glasses, the device protocol
Browser and code sentient/browser, sentient/sandbox Browser control, sandboxed scripts
Voice sentient/voice Speech in and out, wake word
Desktop app desktop/ Electron + React + TypeScript
Packaging packaging/, desktop/electron-builder.yml Installers

Each area's tests live in the matching tests/<area> folder. CLAUDE.md has the deeper conventions; it is written for AI coding assistants but is a good read for people too.

Adding an integration

Copy a small plugin such as sentient/integrations/plugins/trello.py: declare the setup fields, write each tool as a typed async function with a docstring and a Risk, and add tests with mocked HTTP (respx). The desktop app renders the connect screen from your plugin, so most integrations need no UI code.

Using AI coding assistants

Welcome. Point your assistant at CLAUDE.md (also linked from AGENTS.md). How agents work here (testing for real, sharing one computer, what goes in the PR) is in docs/AGENT_WORKFLOW.md. You are still the author: read the diff, run the checks, and make sure the PR description is yours and accurate.

Contributor License Agreement

The first time you open a PR, a bot asks you to agree to our CLA by posting one comment. It lets us keep offering Sentient under the AGPL and fund its development. You only do this once.

Questions, bugs and security

The previous version

Sentient v2 was a cloud web app with its own servers. It now lives on the v2 branch and the v2-final tag, and it is no longer developed. New work goes into v3 on main.

Everyone taking part follows our Code of Conduct.