kot-attendance-bot 1.0.0

Autofill missing King of Time (KOT) time records using Selenium

kot-attendance-bot

Selenium helper for automating King of Time attendance tasks.

Installation

pip install kot-attendance-bot

Setup

On first run, the tool prompts for clock-in, break-start times, and browser selection, then asks whether to save them to config.toml.

Edit config.toml if you want different default times, auto-login, or proxy settings. HTTP_PROXY and HTTPS_PROXY environment variables override values in config.toml.

Credentials

Login is manual unless configured via config.toml or environment variables:

• Environment Variables: Set KOT_USERNAME and KOT_PASSWORD. This automatically enables auto-login.
• Config File: Set auto_login = true and provide username and password.

Note: Auto-login stores the password in plaintext in config.toml. Using environment variables is recommended for better security.

Commands

Fill Missing Records

kot-attendance-bot fill [options]

Opens King of Time, prompts for login (if needed), switches to the requested month, and fills missing time records for weekdays.

• Default visibility: Visible (use --headless to run hidden).
• Default month: Current month (checks previous month first during the first work week).

Holiday Lookup

kot-attendance-bot holiday [options]

Extracts holidays (system holidays and scheduled leaves) for a specific month.

• Default visibility: Headless (use --visible to see the browser).
• Caching: Results are saved in kot-attendance-bot.json to avoid redundant browser sessions.
• Formats: ASCII calendar (default), lines of text (--text), or JSONL (--json).

AI Agent Integration

This project is "Agent-Ready," featuring the kot-attendance-bot-runner skill—a set of procedural instructions that allow AI agents to handle your attendance tasks autonomously. Whether you use Gemini CLI, Claude Code, GitHub Copilot, or Codex, you can simply ask the agent to "fill my missing records" or "check my April holidays," and it will know exactly how to execute the commands with the correct flags and environment variables.

To use the skill:

• Gemini CLI: Install the packaged skill:

  gemini skills install kot-attendance-bot-runner.skill --scope workspace
  /skills reload
  

• Claude Code, Copilot, Cursor, etc.: Point your agent to the kot-attendance-bot-runner/SKILL.md file. The clear, imperative instructions in that file help any LLM-based agent understand the CLI's nuances, headless requirements, and credential handling.

Now you can just delegate your King of Time tasks to your favorite AI assistant!

Options

All commands support these shared options:

• -c, --config PATH: Path to config.toml.
• -b, --browser BROWSER: Browser to use (firefox, chrome, edge, safari).
• --month MONTH: Month number (1-12).
• -y, --auto: Skip runtime confirmations.
• --headless: Run browser in headless mode.
• --visible: Run browser in visible mode.

For holiday specifically:

• --no-cache: Force fresh data fetch from King of Time.
• --text: Output as simple text lines.
• --json: Output as JSONL.

Output Redirection

In headless mode, status and progress messages are sent to stderr, while actual data results (like holiday lists) and interactive prompts are sent to stdout. This allows you to redirect logs without losing the output:

kot-attendance-bot holiday --json 2>/dev/null > holidays.jsonl

Contribution

Setup for Development

This project uses uv for dependency management.

uv sync

Running Tests

uv run python -m unittest discover -s tests

Local Execution

uv run python main.py [command] [options]