IRCv3.2 cap-notify Extension

Copyright © 2014 Attila Molnar <>

Unlimited redistribution and modification of this document is allowed provided that the above copyright notice and this permission notice remains intact.


This client capability MUST be named cap-notify.

The cap-notify client capability allows a client to be notified when the client capability offering (i.e. capabilities listed in CAP LS) on a server changes.

When enabled, the server MUST notify clients about all new capabilities and about existing capabilities that are no longer available via the messages specified in this document.

Implicit vs explicit support

The cap-notify capability MUST be implicitly enabled if the client requests CAP LS with a version of 302 or newer (CAP LS 302), as described in the capability negotiation 3.2 specification. Further, the cap-notify capability MAY NOT be disabled if the client requests CAP LS with a version of 302 or newer.

When implicitly enabled via this mechanism, servers MAY list the cap-notify capability in CAP LS and CAP LIST responses. Additionally client MAY request the capability with CAP REQ, and capable servers MUST accept and CAP ACK the request without side effects.

Clients that do not support CAP LS version 302 MAY request the cap-notify capability explicitly. Such clients MAY disable the capability at any time. This to ease the adaptation of new features.


This specification introduces two new CAP subcommands: NEW and DEL.

Clients implementing this specification SHOULD react to the CAP NEW message with a CAP REQ message if they would like to use one of the newly offered capabilities.

Upon receiving a CAP DEL message, the client MUST treat the listed capabilities cancelled and no longer available. Clients SHOULD NOT send CAP REQ messages to cancel the capabilities in CAP DEL, as they have been canceled already by the server.

Servers MUST cancel any capability-specific behavior for a client after sending the CAP DEL message to the client.

Servers SHOULD NOT remove support for in-use sticky capabilities.

Clients MUST gracefully handle situations when the server removes support for any capability, including sticky capabilities. If the client cannot continue to operate without a capability, disconnecting with an appropriate QUIT message is acceptable.

The format of the new messages is as follows:

CAP <nick> NEW :<extension 1> [<extension 2> ... [<extension n>]]
CAP <nick> DEL :<extension 1> [<extension 2> ... [<extension n>]]

The last parameter in both new messages contain a list of new extensions that became available on the server (in the case of CAP NEW) or a list of extensions that are no longer available (for CAP DEL). The capability list is space separated. If capability negotiation 3.2 was used, extensions listed MAY contain values.


  1. Message indicating that a new extension named batch is now available: CAP modernclient NEW :batch
  2. Message indicating that multiple extensions are no longer available: CAP modernclient DEL :userhost-in-names multi-prefix away-notify
  3. Example showing a client requesting capabilities when they become available:

     Server: CAP tester NEW :away-notify extended-join
     Client: CAP REQ :extended-join away-notify
     Server: CAP tester ACK :extended-join away-notify
  4. Server changes list of supported SASL mechanisms. This example requires client to support both CAP LS 302 and batch:

     Client: CAP LS 302
     Server: CAP * LS :sasl=PLAIN batch
     Client: CAP REQ batch
     Server: BATCH +cap
     Server: @batch=cap CAP client DEL :sasl
     Server: @batch=cap CAP client NEW :sasl=PLAIN,EXTERNAL
     Server: BATCH -cap