Gibi

Gibi is a Slack bot built with TypeScript and the Slack Bolt framework.

Setup & Configuration

Prerequisites

• Node.js (v18+ recommended)
• A Slack Workspace
• Agent CLIs (Optional but recommended):
  • gemini (Google Gemini) - Default
  • claude (Anthropic Claude)
  • cursor (Cursor AI) Ensure these CLIs are installed and available in your system's PATH.

1. Create Slack App & Obtain Tokens (2026 Guide)

The easiest way to configure the bot is using a Slack App Manifest.

1. Navigate to Slack Apps.
2. Click Create New App.
3. Select From an app manifest.
4. Select your target workspace.
5. Paste the following YAML manifest:

display_information:
  name: Gibi
  description: A helpful Slack bot
  background_color: '#2c2d30'
features:
  bot_user:
    display_name: Gibi
    always_online: true
oauth_config:
  scopes:
    bot:
      - chat:write
      - channels:history
      - groups:history
      - im:history
      - app_mentions:read
      - commands
  slash_commands:
    - command: /cd
      description: Change working directory
      usage_hint: '[path]'
      should_escape: false
    - command: /plan
      description: Enter Plan Mode to generate implementation plans
      usage_hint: '[goal]'
      should_escape: false
    - command: /model
      description: Switch the AI model for the current context
      usage_hint: '[model_name]'
      should_escape: false
    - command: /help
      description: Show available commands
      usage_hint: ''
      should_escape: false
    - command: /agent
      description: Switch the backing agent
      usage_hint: '[agent_name]'
      should_escape: false
settings:
  event_subscriptions:
    request_url: http://localhost:3000/slack/events # Ignored for Socket Mode but required for schema
    bot_events:
      - message.channels
      - message.groups
      - message.im
      - app_mention
      - member_joined_channel
  socket_mode_enabled: true

6. Click Next and then Create.
7. Obtain Bot Token:
   • Go to OAuth & Permissions.
   • Click Install to Workspace.
   • Copy the xoxb-... token. This is your SLACK_BOT_TOKEN.
8. Obtain Signing Secret:
   • Go to Basic Information > App Credentials.
   • Copy the Signing Secret. This is your SLACK_SIGNING_SECRET.
9. Obtain App Token:
   • Go to Basic Information > App-Level Tokens.
   • Click Generate Token and Scopes.
   • Name it (e.g., socket-mode), add the connections:write scope, and generate.
   • Copy the xapp-... token. This is your SLACK_APP_TOKEN.

2. Run the Application

1. Install dependencies:

   npm install

2. Start the app:

   npm start

3. On the first run, the app will prompt you to enter the tokens you obtained above. It will securely save them to your system keychain so you don't need to enter them again.

2a. Run as CLI (Global Install)

Alternatively, you can install Gibi globally and run it from any directory:

npm install -g .
gibi

Development

• npm start: Runs the bot in development mode.
• npm run dev: Runs the bot with auto-reload (using nodemon).
• npm run build: Compiles TypeScript to JavaScript.
• npm run lint: Check for linting errors.
• npm run lint:fix: Auto-fix linting errors.
• npm run format: Auto-format code with Prettier.
• npm run format:check: Check if code is formatted.

Features

🏠 App Home Dashboard

Gibi now features a dedicated Home tab in Slack.

• System Status: View available models and agents.
• Recent Activity: See your most recent conversation contexts and their current state (Model, Agent, CWD) at a glance.

📂 Interactive Navigation

The /cd command and cd [path] messages now provide an interactive directory browser.

• Buttons: Navigate into folders by clicking buttons instead of typing paths.
• Quick Up: Use the "Up one level" button for fast traversal.

🛠️ Visual Configuration

Switching models and agents is now easier and less error-prone.

• Modals: Use /model or /agent without arguments to open a popup window with selection dropdowns.

🤖 Rich Agent Responses

Conversation with Gibi is more structured and informative.

• Context Footers: Every response shows which Agent and Model were used, along with the current working directory.
• Feedback: Use the 👍/👎 buttons on responses to provide quick feedback.

Context Awareness & Threading

Gibi now uses a Thread-First approach to keep your channels clean and organized.

• Start a Task: Mention the bot in a channel to start a new context (e.g., @Gibi let's debug this). Gibi will reply in a thread.
• Chat in Thread: Once a thread is started, you can reply directly in that thread without mentioning @Gibi again. The bot will automatically listen and respond within that specific context.
• Noise Reduction: Gibi ignores general channel messages. It only responds to:
  • Direct Mentions (@Gibi)
  • Direct Messages (DMs)
  • Messages within threads it is already participating in.
• Isolation: Each thread is a completely isolated context with its own memory, working directory (CWD), and configuration.

Persistence

Contexts are saved to .context.json locally. If you restart the bot, it picks up right where it left off.

/cd Command

Change the bot's working directory contextually for the current channel.

• Usage: /cd [path]
• Examples:
  • /cd src: Move into the src folder.
  • /cd ..: Move up one level.
  • /cd: Show the current directory listing.
• Note: The directory change is persisted per channel/thread. It does not affect the global process or other channels.

/plan Command

Enter "Plan Mode" where the bot acts as a technical architect to help you plan features.

• Usage: /plan [goal]
• Example: /plan Build a new login system
• Behavior: The bot will generate a detailed markdown plan/checklist and ask clarifying questions.

/model Command

Switch the Gemini model used for the current conversation.

• Usage: /model [model_name]
• Example: /model gemini-1.5-pro
• Note: Persisted per channel/thread.

/agent Command

Switch the backing AI agent used for the conversation.

• Usage: /agent [agent_name]
• Supported Agents: gemini, claude, cursor
• Example: /agent claude
• Note: Persisted per channel/thread. Requires the respective CLI to be installed.

/help Command

Show a list of all available commands and their usage.

• Usage: /help

Troubleshooting

Events Not Firing?

If features like the invite greeting aren't working:

1. Check Event Subscriptions: Ensure the relevant events (e.g., member_joined_channel) are added in the Slack App settings.
2. Reinstall App: After changing permissions or events, you MUST reinstall the app to the workspace.
   • Go to Install App in the sidebar.
   • Click Reinstall to Workspace.