sencre

Connect a coding agent (Claude Code, Kilo Code, Cursor, or any MCP client) to a Sencre board. One command, one project, no tokens to copy and paste.

npx sencre init

Zero runtime dependencies, Node >= 20. The package is a thin stdio proxy: it forwards MCP JSON-RPC to your Sencre board over HTTP and holds no tool definitions of its own, so the tools an agent sees are always exactly what the server defines — not a second, possibly stale copy shipped in this package.

The six subcommands

| Command | What it does | |---|---| | npx sencre init | Wires this project's agents to a board: offers every client it knows about with the ones it finds here pre-ticked, shows every file it is about to write, asks for confirmation, then runs the sign-in flow. | | npx sencre login | Authorizes this workspace (opens a browser). Use it to sign in again after logout, or to renew a session init could not renew silently. | | npx sencre logout | Revokes this workspace's token on the server and deletes the local session. Safe to run twice. | | npx sencre status | Prints what this workspace is connected to: server, token validity, the live project name/id, and per-column card counts. | | npx sencre doctor | Diagnoses a broken setup — see below. --fix re-applies the file-level fixes before reporting. | | npx sencre mcp | The stdio MCP proxy itself. Your agent runs this; you never type it directly. |

Flags: --yes (init: write without asking — see the note on rebinding below, this does not cover it), --rebind (init: see below), --fix (doctor), --server <url> (init, login: which board to authorize against; defaults to https://sencre.tr), --root <path> (any command: the directory to work in, instead of the current one), --help / -h.

What init writes

Nothing is written until you have seen the full list and said yes (--yes skips the prompt, not the preview):

• A config entry for every coding-agent client you select — pre-ticked from what this command finds installed in the current directory: Claude Code (detected by .claude/ or .mcp.json, written to .mcp.json), Kilo Code (detected by .kilo/, written to .kilo/kilo.jsonc or an existing .kilo/mcp.json — see below), and Cursor (detected by .cursor/, written to .cursor/mcp.json). Only the sencre entry inside that file is added or replaced; every other server entry and every unrelated key is left exactly as it was.
• One .gitignore line (.sencre/), added only if nothing already covers it.
• A marked block in AGENTS.md, between <!-- sencre:start --> and <!-- sencre:end -->, so it can be refreshed later without touching the rest of the file.
• A marked block in CLAUDE.md (<!-- sencre:claude-code-start --> … <!-- sencre:claude-code-end -->) holding one @AGENTS.md import, for a selected Claude Code — which reads CLAUDE.md and not AGENTS.md. A file that already imports it is left alone.
• .sencre.json — the project this workspace is bound to (projectId, name). This is the file worth committing: it is what tells every teammate's agent which board to talk to, and it carries nothing secret.
• .sencre/session.json — the OAuth token, written only after a browser sign-in succeeds. This one is not meant to be shared; see below.

init does not approve itself. Claude Code asks before running the servers a project declares in .mcp.json, and until you accept that prompt the tools do not load — npx sencre doctor reports the missing approval as a note, and init offers once, at the end, to record it in .claude/settings.local.json. The offer defaults to no, and --yes does not cover it — same as rebinding (see below).

Which agents get configured

init lists every coding agent it knows about — Claude Code, Kilo Code, Cursor — with the ones it found in this workspace already ticked. Move with ↑↓, toggle with space, confirm with enter. Whatever is ticked is what gets configured, so an agent this tool cannot see is one keystroke away instead of silently skipped. Ctrl+C at the list aborts the whole run: init prints Aborted. Nothing was written. and exits 1, same as declining the Continue? prompt.

Nothing is remembered. Ticking a client writes its config, and that config is what makes the client detectable, so the next run finds it already ticked. Unticking means "not this run": doctor still reports a client that is installed here and not wired up, because that is still true.

--yes, a pipe, or any run without a terminal skips the list and configures whatever was detected — the behaviour every earlier release had.

If that ends with no client at all, init writes no client config and instead prints the URL a remote client (a Claude.ai or ChatGPT connector, for instance) would connect to. Nothing about that is an error — those clients aren't files on disk to detect.

The one question init asks about your code

At the very end, on a terminal only, init asks whether your agent may read this project once and write a short summary of what it is. The board's AI reads that summary when it suggests cards, so its suggestions can be about your project instead of about software in general.

The read is your agent's, on your tokens and your time — which is the only reason this is a question. It defaults to no, and --yes skips it entirely and never grants it: a consent a flag can give is not a consent.

Saying no skips only that one read. The summary still gets written, a little at a time, as work ships here — declining is not a way to turn the summary off. Owners and admins can read, edit or clear it from the board's project settings.

The answer is stored in .sencre/preferences.json, which is per-machine and gitignored, so it is yours rather than the repository's, and logout does not revoke it. Declining stores nothing at all, so the next init asks again.

Kilo Code's config path is genuinely unsettled

Kilo Code's own current documentation places project-level MCP config at .kilo/kilo.jsonc, but older releases (and some still-open issues in its tracker) read a plain .kilo/mcp.json instead. init handles both without guessing which your installed version reads: if .kilo/mcp.json already exists, it is reused; only a workspace with neither file gets the new .kilo/kilo.jsonc default. Whichever file it picks, only the mcp.sencre key is written.

Rebinding — a workspace's project never changes silently

.sencre.json records which project this workspace talks to. If you sign in to a different project than the one already recorded there, init refuses and exits 1 rather than quietly repointing your board. This is deliberate: a committed .sencre.json is a promise to your teammates about which board their agent will read and write, and nothing should be able to break that promise by accident.

Neither --yes nor answering "yes" at the prompt authorizes a rebind — only the explicit --rebind flag does:

npx sencre init --rebind

If you actually want the other project, either pass --rebind, or run npx sencre logout first and sign in with the account that owns the project already recorded in .sencre.json.

The token never leaves the workspace

There is no global session file and no ~/.sencre/ directory anywhere on your machine. The only place a token is ever written is <workspace>/.sencre/session.json, created with the directory at file mode 0700 and the session file itself at 0600, written atomically (write, then rename) under a lock so a crash or a second concurrent process can never leave a half-written or duplicated token on disk. init adds .sencre/ to .gitignore in the same run that first creates it, so the ordinary path never risks a commit.

If you are migrating from the older sencre-mcp package: that package's ~/.sencre/session.json is never read by this one. It is safe to delete once every workspace using it has moved to npx sencre init.

doctor

Checks, in the order a human would debug them: is this directory (or a parent) a workspace at all; is there a session and is its token valid or renewable; does the token's project agree with .sencre.json; does the server answer; does every detected client's config actually carry the current sencre entry; is .sencre/ gitignored; and — the one failure mode nothing else surfaces — does this directory resolve to the same workspace a client spawned here would resolve. Each failing line prints the exact command that fixes it. --fix re-applies the file-level fixes (client configs, .gitignore, the AGENTS.md block) before reporting; it never signs in and never touches .sencre.json.

Known limitation: the sencre entry init/doctor --fix writes into a client config is replaced wholesale on every run. If you hand-edit that entry (to add an environment variable, say), the next init or doctor --fix overwrites it, and doctor reports it as not matching rather than as customized. Don't hand-edit it.

Tools an agent sees

Everything board-related is forwarded to the server unchanged — board, add_tasks, update_tasks, move_tasks, delete_tasks, add_checklist, check_items, status, set_project_summary, set_language — so a stdio client and an HTTP client always see the exact same tool set; this package defines none of them. (A plan’s tasks belong on a phase card via add_checklist, not as their own cards.) Two more tools exist only in this proxy, because they act on your machine's filesystem and browser rather than the board: login (opens the browser sign-in; what an agent is told to call when a tool result names npx sencre login as the fix) and logout.

Remote clients (Claude.ai, ChatGPT connectors)

Those connect over Streamable HTTP directly to the server and never install this package at all — init prints the URL to give them when it does not find a local client config to write to.

License

MIT