IRC Guides · Bots

Eggdrop TCL scripting basics

Intermediate · about 20 min read

Eggdrop is controlled largely by Tcl scripts. This guide covers safe loading, the most common binds, and a minimal working example. Official reference: Eggdrop Tcl commands.

Prerequisite: a working bot — see Install & configure Eggdrop. Scripts are available under Eggdrop TCL Scripts.

1. Load a script safely

1. Download a .tcl (or unpack a .tcl.gz) into your bot’s scripts/ directory.
2. Read the file before loading — unknown scripts can run shell commands or steal the userfile.
3. In your bot config (or from the partyline), source it:

source scripts/myscript.tcl

On the partyline after the bot is running:

.rehash
# or load once:
.tcl source scripts/myscript.tcl

2. Binds (reacting to IRC)

A bind connects an IRC event to a Tcl procedure. Common types:

• pub — public channel message
• msg — private message to the bot
• join / part / sign — channel traffic
• nick — nick changes
• raw — raw server lines (advanced)
• time — clock-based triggers

bind pub - !hello hello:pub

proc hello:pub {nick uhost hand chan text} {
  putserv "PRIVMSG $chan :Hello, $nick!"
}

Flags after the bind type (- above) restrict who may trigger it (e.g. o for ops). See the docs for the full flag list.

3. Minimal public command

Save as scripts/hello.tcl and source it:

# scripts/hello.tcl — minimal example for IRCPlus guides
bind pub - !ping ping:cmd

proc ping:cmd {nick uhost hand chan text} {
  putserv "PRIVMSG $chan :Pong, $nick."
}

putlog "hello.tcl loaded: use !ping in channel"

Useful output commands:

• putserv — send a raw line to the IRC server
• puthelp / putquick — queued output (prefer these to avoid excess flood)
• putlog — write to the bot console/log

4. Timers

# run once after 60 seconds
timer 60 { putlog "one minute passed" }

# repeating every 300 seconds (5 minutes)
utimer 300 my:repeat
proc my:repeat {} {
  putlog "tick"
  utimer 300 my:repeat
}

timer uses minutes in older docs in some contexts — on modern Eggdrop, check timer/utimer in the Tcl command list for your version. Prefer utimer (seconds) for clarity.

5. Tips and pitfalls

• Match script version to your Eggdrop major version (1.6 vs 1.8 vs 1.10) when possible
• One feature per script at first — easier to debug
• Use catch around risky operations so one error does not kill the whole script
• After editing, .rehash or reload the single file; watch the partyline for Tcl errors
• Channel text is untrusted input — validate before using it in file or shell operations