seepdeek

modular discord bot. auto-responds to @mentions and replies using deepseek, with tool calling for custom embeds, file attachments, no-response-with-reason, and tagscript execution.

setup

git clone <this-repo> seepdeek
cd seepdeek
npm install

1. environment variables

copy .env.example to .env and fill in the required values:

cp .env.example .env

var	required	description
DISCORD_TOKEN	yes	bot token from discord developer portal
OWNER_ID	yes	your discord user id (enables admin commands)
DEEPSEEK_API_KEY	yes	deepseek api key
DISCORD_BOT_ID	no	auto-detected on first login if left blank
DEEPSEEK_BASE_URL	no	default https://api.deepseek.com/v1
DEEPSEEK_MODEL	no	deepseek-chat (v3) or deepseek-reasoner (r1)
DEEPSEEK_MAX_TOKENS	no	default 2048
DEEPSEEK_TEMPERATURE	no	default 0.8
SYSTEM_PROMPT_PATH	no	default ./data/systemPrompt.txt
MAX_CONTEXT_MESSAGES	no	rolling history per channel, default 20
NO_RESPONSE_REASON_TTL_MS	no	how long no_response reason stays before deletion, default 8000
ALLOWED_ATTACH_PATHS	no	semicolon-separated absolute dirs the ai may read files from (empty = disabled)
MAX_ATTACHMENT_BYTES	no	cap on attachment size, default 25MB
TAGS_WRITE_DIR	no	where save_tag writes new tags, default ./data/tags
TAGSCRIPT_DOCS_PATH	no	path to tagscript reference doc
DISABLED_MODULES	no	comma-separated module names to silence
TAG_ENGINE_PATH	no	override path to your tag-engine.js
TAGS_DIR	no	override path to your tags folder

2. configuration

copy config.json.example to config.json and edit it:

cp config.json.example config.json

{
  // user IDs that can run mod commands (?warn, ?report, ?clear)
  "modUsers": [],

  // user IDs that get auto-blocked with a custom message
  "blockedUsers": [],
  "blockedUserMessage": "leave me alone",

  // customizable status messages
  "messages": {
    "thinkingTag": "🤔 running tag...",
    "aiStatus": "thinking..."
  },

  // custom emoji IDs (use your own server's emoji IDs)
  "emojis": {
    "seepdeek": "<:seepdeek:1514712868539469975>",
    "reaction": "1514713773863207154"
  },

  // word censorship (curseMap) and slur blocking (slurs)
  // leave empty to disable
  "censorship": {
    "curseMap": {},
    "slurs": []
  }
}

3. system prompt

edit data/systemPrompt.txt to set the bot's personality and instructions.

4. run

npm start

for development with auto-restart on file changes:

npm run dev

features

• auto-respond on @mention or reply using deepseek
• tool calling: embeds, file attachments, no-response, tagscript execution
• tagscript engine: create, run, and manage tags via ai or commands
• conversation memory: per-channel rolling history
• modular: drop-in modules under src/modules/
• slash commands: /ask, /tag, /tags, /save-tag, /forget, /stop, /roll, etc.
• MCP support: connect external tool servers via bb!?addmcp

commands

user commands

command	description
?tags	list all tags
?tag <name> [args]	run a tag
?raw <name>	view tag source
?stats	show context memory stats
?seepdeek [path]	view source files
?stop	abort current ai request
?clear	clear conversation memory (mod only)
?clearvote	vote to clear context (3 votes needed)
?help	show help

mod commands (require modUsers or owner)

command	description
bb!?warn <user> <reason>	warn a user
bb!?report <user> <reason>	file a report
bb!?reports [filter]	view reports
bb!?ban <user> <reason> [time]	ban a user
bb!?unban <user>	unban a user
bb!?timeunban <user> <reason> <time>	temp unban
bb!?setnick <user> <nick>	change nickname
bb!?rmtag <name>	force delete a tag
bb!?disable / bb!?enable	toggle bot in channel
bb!?inject <text> / bb!?uninject	inject system prompt text

slash commands

/ask, /tag, /tags, /save-tag, /read-tag, /delete-tag, /ping, /stats, /forget, /stop, /roll, /optout, /optin, /ban, /unban

modules

every folder under src/modules/ is auto-loaded as a module. a module exports:

module.exports = {
  name: 'my-module',
  description: 'optional description',

  async init(ctx) { },

  commands: [
    { data: new SlashCommandBuilder()..., async execute(interaction) { } }
  ],

  events: {
    messageCreate: async (message, client) => { },
  },

  tools: [
    {
      name: 'do_thing',
      description: 'does the thing',
      parameters: { type: 'object', properties: { ... } },
      async execute(args, ctx) {
        return { ok: true, forModel: 'result description' };
      },
    },
  ],
};

built-in modules

• core-tools — make_embed, attach_file, no_response, /ping
• deepseek-auto — auto-respond on mention/reply, /ask, /forget, /stop
• tagscript — tag engine wrapper, /tag, /tags, /save-tag
• admin — /ban, /unban, /inject, /uninject
• mcp — connect external MCP tool servers
• optout — /optout, /optin
• example — roll_dice, remember_note, /roll

testing

node smoke.js

layout

seepdeek/
├── package.json
├── config.json              # bot configuration (gitignored)
├── config.json.example      # config template
├── .env                     # environment variables (gitignored)
├── .env.example             # env template
├── smoke.js
├── data/
│   ├── systemPrompt.txt     # ai system prompt
│   ├── tags/                # saved tags
│   └── ...                  # runtime data (bans, memory, etc.)
└── src/
    ├── index.js             # entry point
    ├── core/                # config, client, logger, registry, etc.
    ├── ai/                  # deepseek client, agent executor, helpers
    └── modules/             # feature modules