agentleFS
arthurcuriarthurcuri/mcp-instructure-canvas/docs/agents.md

mcp-instructure-canvas

AGENTS.md2 starsChanged 34 days agoMITView on GitHub

The local agent lets the owner of a private Telegram chat ask Codex or Claude Code for help with Canvas assignments. It is separate from the MCP server and deadline reminders. It uses the account authenticated in the selected CLI, creates its own conversation, and does not import existing web chats. Use a source checkout with dependencies installed, a configured Canvas .env, and a dedicated Telegram bot. Follow Telegram setup first. Keep one update consumer per bot: stop other receivers…

  • Reads credentials
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository4 other files it gives its agents.

The file

We split this agents.md into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use a source checkout with dependencies installed, a configured Canvas .env, and a dedicated Telegram bot.

    line 5

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
agents.md

Optional Telegram agents

The local agent lets the owner of a private Telegram chat ask Codex or Claude Code for help with Canvas assignments. It is separate from the MCP server and deadline reminders. It uses the account authenticated in the selected CLI, creates its own conversation, and does not import existing web chats.

Use a source checkout with dependencies installed, a configured Canvas .env, and a dedicated Telegram bot. Follow Telegram setup first. Keep one update consumer per bot: stop other receivers before switching providers or running chat discovery.

Choose the provider and account

uv run canvas-agent setup

Setup is interactive. It asks you to choose Codex or Claude, review an existing subscription account or explicitly open native login, choose manual/automatic mode, and review saving or starting services. It only saves provider/mode choices to .env, preserving tokens and private notes. No provider is selected implicitly.

You can save without starting. Existing services then keep their old configuration until explicitly restarted. --provider codex or --provider claude overrides the saved provider for one command without saving a preference.

uv run canvas-agent status
uv run canvas-agent start
uv run canvas-agent stop

On macOS, Codex start installs a local LaunchAgent. The computer must be awake, signed in, and online; no open Terminal is required. On other systems, use canvas-agent run --provider codex in the foreground or manage it with your own supervisor. The runtime does not install a Linux service automatically.

Codex with ChatGPT

Install Codex CLI and authenticate using your ChatGPT account through setup or codex login. The agent rejects API-key authentication. Setup reads native account metadata without starting a model task.

uv run canvas-agent setup --provider codex
# Foreground alternative after account/configuration setup:
uv run canvas-agent run --provider codex

The receiver uses Codex App Server over stdio, with normal provider permissions and owner-only polling. It accepts text and quoted messages, returns final text, and can attach requested coursework files. Incoming file, audio, and image messages are not supported by this receiver.

Bot command or messageBehavior
/start, /helpShow help without model calls
/statusShow state and pending approvals without model calls
/cancelRequest interruption of the active turn
/resetStart another conversation on the next request; retain coursework files
/approve CODE, /deny CODEAnswer the corresponding current permission request
Yes / NoAnswer a single pending simple confirmation; Portuguese replies remain accepted
/answer CODE responseAnswer a question; real forms still require the requested fields
Text during an active taskAdd context/corrections to the same turn
A new text requestStart model work using the provider's quota

Approvals expire after 15 minutes. If several requests are pending, reply to the specific Telegram request or use its code. Arbitrary text is never treated as permission. Receiver tasks have a 30-minute limit; interrupted requests are not replayed after restart.

The bot keeps the native conversation and a private assignment reference. Current owner corrections take priority over older references and the default course. A cloud reminder is not an inbound agent message: use Reply on it or send the assignment link. For an unquoted “this assignment,” the receiver reads current deadlines across courses; if several match, the agent must ask which one. Reference data never grants write authorization.

Requested attachments must be inside .local/activities/. The English marker [[file: relative/path]] and legacy [[arquivo: relative/path]] are supported. Configuration files, credentials, paths outside that directory, and oversized files are rejected.

Claude Code with Claude

Install Claude Code and Bun. Open claude in the project and accept its workspace trust prompt. Authenticate through setup or the official CLI flow. The agent uses subscription authentication and normal permissions.

Install the official Channels plugin:

claude plugin install telegram@claude-plugins-official --scope local
uv run canvas-agent setup --provider claude
uv run canvas-agent status

Claude replies and approvals use the official plugin. Team/Enterprise administrators must allow Channels; organization policy cannot be bypassed. See Claude Channels. This integration has mocked coverage, but live verification in the maintainer's Team account was blocked by organization policy.

For foreground use, run uv run canvas-agent run --provider claude. Idle background sessions may stop; inspect claude agents and pin the session when needed. Preparation writes private state under .local/agent/, including the Telegram credential copy required by the plugin. After changing credentials or mode, explicitly stop/start to refresh the runtime copy.

Manual and automatic mode

Manual mode is the default:

CANVAS_AGENT_AUTO=false

The agent waits for an owner request. Preparing an explanation or file does not authorize a Canvas submission; request submission explicitly and identify the assignment and content.

Setting CANVAS_AGENT_AUTO=true is advance authorization for a separate local worker to prepare and submit eligible pending assignments. It requires CANVAS_READ_ONLY=false. Choose it in setup and review activation, or deliberately edit .env and restart the selected provider. Installation does not enable it.

On macOS, automatic mode installs an 08:00 daily job in the system timezone. CANVAS_TIMEZONE affects report dates, not the local scheduler's clock. On Linux, schedule the worker yourself. The worker can run without a bot receiver and does not consume inbound updates.

uv run canvas-agent auto-run --provider codex
# Alternative provider:
uv run canvas-agent auto-run --provider claude

With automatic mode disabled, these commands exit without reading assignments or calling models. To disable an installed worker, restore false and explicitly stop/start the service.

The worker scans all active courses and processes supported, available text/file/URL assignments sequentially, including undated or overdue work when submission remains open. Quizzes, external tools, paper assignments, and locked tasks are excluded. Missing personal data, empirical results, or additional permissions require attention; fabricated evidence and placeholder submissions are not acceptable.

Each attempt is claimed in .local/agent-auto/ledger.json before inference. A separate Canvas API read verifies submission afterward; model text is not proof. Attempted, failed, and uncertain tasks are not retried automatically. Inspect Canvas before requesting continuation. Provider permissions and quota limits still apply. Cloud reminder jobs only read Canvas and do not call these agents.

Troubleshooting

SymptomAction
No provider selectedRun canvas-agent setup or pass an explicit provider
Bot does not answer /startCheck service status, private chat, network, and a single poller
Telegram HTTP 409Another poller or webhook is using the bot
Approval still waitingUse the current request/code; simple confirmations accept Yes/No, forms need fields
Wrong assignment selectedReply to the current reminder or send the current assignment URL
Missing real conversation historyUse /reset to start another thread; files remain; inspect Canvas before repeating submissions
Claude blocked_by_organizationAdministrator must enable Channels before receiving messages
Changed mode not reflectedStop/start to refresh the private runtime configuration
Automatic worker inactiveCheck opt-in, write mode, provider login, installed job, and system timezone
needs_attention in ledgerRead the reason and inspect Canvas; supply missing information or request continuation
Provider quota/login expiredStop, renew native login, and start again

State/logs under .local/codex-agent/, .local/agent/, and .local/agent-auto/ are private and ignored. Old updates are discarded on first installation; send a fresh request. Telegram retains updates for a limited time, so prolonged downtime can lose messages. Outbound messages and Canvas writes are never retried automatically after uncertain delivery.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.